Skip to Content

User endpoints in the REST API

The following section provides a list of supported endpoints for users and details about running these endpoints. For more information about users, see User access and keys. 

Before you run an endpoint, you must authenticate yourself. For more information, see Access and authentication for the REST API.

GET /ims/api/v1/userinfo
Get details about the logged-on user
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/userinfo
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/userinfo?preferences=true&gs_product_id=aa
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
  "user_id": "559311222845550",
  "first_name": "Stuart",
  "last_name": "McGill",
  "full_name": "Stuart McGill",
  "principal_id": "administrator",
  "email": "Stuart@bmc.com",
  "user_status": "ENABLE",
  "type": "PERSON",
  "auth_type": "IMS_AUTH",
  "tenant_id": "1903033870",
  "tenant_name": "csbmc",
  "tenant_domain_name": "xxxx-xxx-qa.xxx-cs.bmc.com",
  "trial_expiry_time": "2020-10-21T11:48:09.836578",
  "roles": [
    "407740385418284",
    "826790797684840",
    "637441862780368"
 ],
  "groups": [
    "961971749430087"
 ],
  "permissions": [
    "*"
   "preferences":    [
            {
         "key": "GS_DATA_COLLECTION_FOR_QUALITY_CONSENT",
         "value": "FALSE",
         "level": "TENANT"
      },
            {
         "key": "GS_DATA_COLLECTION_FOR_OUTREACH_CONSENT",
         "value": "FALSE",
         "level": "TENANT"
      },
            {
         "key": "GS_DATA_COLLECTION_FOR_QUALITY_CONSENT",
         "value": "TRUE",
         "level": "USER"
      },
            {
         "key": "GS_DATA_COLLECTION_FOR_OUTREACH_CONSENT",
         "value": "TRUE",
         "level": "USER"
      }
        {
            "key": "GS_TRACK_USAGE",
            "value": "false",
            "level": "USER"
        },
    ]
}
Unsuccessful response
{
   "timestamp": "2022-04-11T10:30:14.345501Z",
   "code": 500,
   "message": "INTERNAL_SERVER_ERROR",
   "error": "Some error while processing the request. Please check logs for details. (ErrorId:87187baf-e4fc-4500-9d8b-91cf0b84891d)"
}
GET /ims/api/v1/users
Get all users under a tenant

You need list permissions to be able to run this API endpoint.

Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/users?page={pagenumber}&size={records}&orderBy=created_date_time&sortOrder=asc&userTypes={usertypes}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "records": [
    {
     "user_id": "811597463253119",
     "principal_id": "ma",
     "tenant_id": "1324710355",
     "email": "mike@gmail.com",
     "first_name": "Mike",
     "last_name": "Adams",
     "full_name": "Mike Adams",
     "status": "ENABLE",
     "type": "PERSON",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-09-30T07:09:29.988165"
    },
    {
     "user_id": "238076465729611",
     "principal_id": "HaRoEgdK",
     "tenant_id": "1324710355",
     "email": "harvey@gmail.com",
     "first_name": "Harvey",
     "last_name": "Ross",
     "full_name": "Harvey Ross",
     "status": "ENABLE",
     "type": "PERSON",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-10-05T17:48:01.389266"
    },
    {
     "user_id": "135817356805491",
     "principal_id": "X4DT1TV81PF7SRCQQUJU0U14EI1FO7",
     "tenant_id": "1903033870",
     "first_name": "1903033870@1602071325210",
     "full_name": "1903033870@1602071325210",
     "status": "ENABLE",
     "type": "API",
     "auth_type": "IMS_AUTH",
     "created_date_time": "2020-10-07T11:48:45.231176"
    }
  ],
 "_metadata": {
   "page": 0,
   "records_per_page": 1000,
   "page_count": 1,
   "total_count": 3
  }
}
Unsuccessful response
{
 "timestamp": "2020-10-07T18:39:26.757790Z",
 "code": 400,
 "message": "BAD_REQUEST",
 "error": "Invalid user type value provided:: XYA"
}
POST /ims/api/v1/users
Create a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "auth_type": "string",
 "email": "string",
 "first_name": "string",
 "full_name": "string",
 "last_name": "string",
 "principal_id": "string"
}
Example request body
{
  "auth_type": "IMS_AUTH",
  "email": "patrickja@gmail.com",
  "first_name": "Patrick",
  "full_name": "Patrick James",
  "last_name": "James",
  "principal_id": "pjames"
}
Parameters
Successful response
{
 "user_id": "484195167480201"
}
Unsuccessful response

Scenario 1: You try to create a user with the same details as that of an existing user.

{
 "timestamp": "2020-10-07T19:08:09.822112Z",
 "code": 500,
 "message": "INTERNAL_SERVER_ERROR",
 "error": "RSSO Service error - User already exists."
}

Scenario 2: You try to create a user without one or more of the mandatory parameters.

{
 "timestamp": "2020-10-07T19:09:55.751212Z",
 "code": 2300,
 "message": "Users First Name and Last Name are required",
 "error": "BAD_REQUEST"
}
DELETE /ims/api/v1/users/{id}
Delete a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:18:27.449791Z",
 "code": 1100,
 "message": "User not found.",
 "error": "Failed to find user by id [980110334580797]"
}
GET /ims/api/v1/users/{id}
Get details of a specific user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Parameters
Successful response
{
  "user_id": "980110334580776",
  "principal_id": "Pcumminss",
  "tenant_id": "1324710355",
  "email": "patca@autostaging.com",
  "first_name": "Pat",
  "last_name": "Cummins",
  "status": "ENABLE",
  "type": "PERSON",
  "auth_type": "IMS_AUTH",
  "created_date_time": "2020-10-07T19:11:23.871605"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:32:17.492948Z",
 "code": 1100,
 "message": "User not found.",
 "error": "Failed to find user by id [980110334580777]"
}
PATCH /ims/api/v1/users/{id}
Update general details of a user
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "email": "string",
 "first_name": "string",
 "full_name": "string",
 "last_name": "string"
}
Example request body
{
  "email": "Pete_Adams@bmc.com",
  "first_name": "Pete",
  "full_name": "Pete Adams",
  "last_name": "Pete Adams"
}
Parameters
Successful response
{
 "message": "SUCCESS"
}
Unsuccessful response
{
 "timestamp": "2020-10-07T19:49:04.118761Z",
 "code": 401,
 "message": "Unauthorized",
 "error": "Unauthorized to perform this operations."
}
POST /ims/api/v1/users/search
Search for users
Request URL
https://<BMC Helix Portal URL>/ims/api/v1/users/search
Request URL with optional parameters
https://<BMC Helix Portal URL>/ims/api/v1/users/search?page={pageNumber}&size={records}&orderBy=created_date_time&sortOrder=asc
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>
Request body
{
 "filters": [
   {
     "field": "string",
     "values": [
       "string"
      ]
   }
  ]
}
Example Request body
{
 "filters": [
   {
     "field": "first_name",
     "values": [
       "Mike", "Sheldon"
      ]
   },
   {
     "field": "type",
     "values": [
       "PERSON",
       "EXTERNAL_PERSON",
       "API"
      ]
   }
  ]
}
Parameters
Successful response
{
  "records": [
    {
      "user_id": "927064703261803",
      "principal_id": "Test",
      "tenant_id": "718542488",
      "email": "test@gmail.com",
      "first_name": "Test",
      "last_name": "auto",
      "full_name": "Test auto",
      "status": "ENABLE",
      "type": "PERSON",
      "auth_type": "IMS_AUTH",
      "created_date_time": "2020-10-14T09:47:11.449072"
    }
 ],
  "_metadata": {
    "page": 0,
    "records_per_page": 1000,
    "page_count": 1,
    "total_count": 1
  }
}
Unsuccessful response
{
   "records": [],
   "_metadata": {
       "page": 0,
       "records_per_page": 1000,
       "page_count": 0,
       "total_count": 0
   }
}
patch/ims/api/v1/users/{id}/status
Update the status of a user (activate or deactivate a user)
Request URL
 https://<BMC Helix Portal URL>/ims/api/v1/users/{id}/status
Request header
Content-Type: application/json
Authorization: Bearer <JWT_token>

Request body

{
    "user_status":"ENABLE/DISABLE"
}
Parameters

Successful response

{       
     "message": "SUCCESS"
}
Unsuccessful response

Scenario: Invalid user ID

{
  "timestamp": "2022-08-17T10:46:08.093251Z",
  "code": 2300,
  "message": "BAD_REQUEST",
  "error": "User with id 324 not found."
}

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Helix Portal 25.4