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. 

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": "559311632847350",
  "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",
  "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"
      }
   ]
}
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
   }
}