Skip to Content
Information

This site will undergo a brief period of maintenance on Thursday, 23 April at 2:30 AM Central/1:00 PM IST. During a 30 minute window, site availability may be intermittent.

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 23.4