User group endpoints in the REST API
The following section provides a list of supported endpoints for user groups and details about running these endpoints. For more information about how user groups can be useful, see User-groups
For information about the supported user endpoints, see User-endpoints-in-the-REST-API.
Before you run an endpoint, you must authenticate yourself. For more information, see Access-and-authentication-for-the-REST-API.
POST /ims/api/v1/groups
Create a user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Request body
"description": "string",
"name": "string"
}
Example request body
"description": "Group for Operators",
"name": "Operators"
}
Parameters
Successful response
"group_id": "555568022225499"
}
Unsuccessful response
"timestamp": "2020-10-05T07:29:49.150974Z",
"code": 400,
"message": "BAD_REQUEST",
"error": "name Operator already exists."
}
GET /ims/api/v1/groups
Get all user groups under a tenant
Request URL
Request URL with optional parameters
Request header
Authorization: Bearer <JWT_token>
Parameters
Successful response
"records": [
{
"name": "Administrators",
"description": "Group of users with tenant administrator permissions.",
"system_object": true,
"group_id": "172058502313325"
},
{
"name": "Admins",
"description": "Admins group",
"system_object": true,
"group_id": "209102834577001"
},
{
"name": "Viewers",
"description": "Viewers group",
"system_object": true,
"group_id": "832875755873939"
},
{
"name": "Monitoring Administrators",
"description": "Monitoring Administrators group",
"system_object": true,
"group_id": "646537009286276"
},
{
"name": "Monitoring CS Administrators",
"description": "Monitoring CS Administrators group",
"system_object": true,
"group_id": "802668222332039"
},
{
"name": "ITSM Insight Administrators",
"description": "ITSM Insight Administrators",
"system_object": true,
"external_id": "10f1bb27-2e1e-402d-bcc4-ec999564a194",
"group_id": "861163279423440"
},
{
"name": "Problem Identification User",
"description": "Problem Identification User",
"system_object": true,
"external_id": "11f1bb27-2e1e-402d-bcc4-ec999564a194",
"group_id": "701228884763254"
},
{
"name": "ITSM Identification User",
"description": "ITSM Identification User",
"system_object": true,
"external_id": "15f1bb27-2e1e-402d-bcc4-ec999564a194",
"group_id": "172421019472008"
},
{
"name": " Viewers",
"description": " Viewers",
"system_object": true,
"external_id": "19f1bb27-2e1e-402d-bcc4-ec999564a194",
"group_id": "548755735505614"
},
{
"name": "RBAC Admins",
"system_object": false,
"group_id": "513653507292122"
},
{
"name": "Viewers",
"system_object": false,
"group_id": "815123392720773"
},
{
"name": "ADE ITSM Insight Administrator",
"description": "ADE ITSM Insight Administrator",
"system_object": true,
"external_id": "AGGADG09FCNVHAQKYT0UQKYT0U8AO9",
"group_id": "557119297948906"
},
{
"name": "ADE Predictive Insights",
"description": "ADE Predictive Insights",
"system_object": true,
"external_id": "AGGADG09FCNVHAQKYTORQKYTOR8CIW",
"group_id": "149088488406951"
},
{
"name": "ADE Incident Correlation User",
"description": "ADE Incident Correlation User",
"system_object": true,
"external_id": "AGGADG09FCNVHAQKYTMLQKYTML8CAQ",
"group_id": "931246876045909"
}
],
"_metadata": {
"page": 0,
"records_per_page": 1000,
"page_count": 1,
"total_count": 66
}
}
DELETE /ims/api/v1/groups/{id}
Delete a user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Parameters
Successful response
"message": "SUCCESS"
}
Unsuccessful response
"timestamp": "2020-10-07T07:13:02.895052Z",
"code": 1200,
"message": "Group not found.",
"error": "Group with id: 154927585141310 not found."
}
GET /ims/api/v1/groups/{id}
Get details of a specific user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Parameters
Successful response
"name": "Administrators",
"description": "Group of users with tenant administrator permissions.",
"system_object": true,
"users": [
{
"user_id": "786532229118438"
},
{
"user_id": "246274386859172"
},
{
"user_id": "939428113782553"
}
],
"group_id": "172058502313325"
}
Unsuccessful response
"timestamp": "2020-10-07T07:14:39.912345Z",
"code": 1200,
"message": "Group not found.",
"error": "Group with id: 154927585141310 not found."
}
PATCH /ims/api/v1/groups/{id}
Update general details of a user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Request body
"description": "string",
"name": "string"
}
Example request body
"description": "This is a new group",
"name": "Admins2"
}
Parameters
Successful response
"message": "SUCCESS"
}
Unsuccessful response
"timestamp": "2020-10-07T07:33:31.352710Z",
"code": 1200,
"message": "Group not found.",
"error": "Group with id: 154927585141310 not found."
}
PATCH /ims/api/v1/groups/{id}/users
Update users associated with a user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Request body
"users": [
{
"id": "string",
"op": "string"
},
{
"id": "string",
"op": "string"
}
]
}
Example request body
"users": [
{
"id": "238076465729611",
"op": "add"
},
{
"id": "444476211329226",
"op": "remove"
}
]
}
Parameters
Successful response
"message": "SUCCESS"
}
Unsuccessful response
"timestamp": "2020-10-07T09:34:32.618926Z",
"code": 400,
"message": "BAD_REQUEST",
"error": "user_id 1087289297545 does not exist."
}
PUT /ims/api/v1/groups/{id}/users
Replace users associated with a user group
Request URL
Request header
Authorization: Bearer <JWT_token>
Request body
"users": [
{
"user_id": "string"
},
{
"user_id": "string"
}
]
}
Example request body
"users": [
{
"user_id": "444476211329226"
},
{
"user_id": "238076465729611"
}
]
}
Parameters
Successful response
"message": "SUCCESS"
}
Unsuccessful response
"timestamp": "2020-10-07T09:34:32.618926Z",
"code": 400,
"message": "BAD_REQUEST",
"error": "user_id 1087289297545 does not exist."
}
POST /ims/api/v1/groups/search
Search user groups
Request URL
Request URL with optional parameters
Request header
Authorization: Bearer <JWT_token>
Request body
"filters": [
{
"field": "string",
"values": [
"string"
]
}
]
}
Example request body
"filters": [
{
"field": "*",
"values": [
"Parent Group"
]
}
]
}
Parameters
Successful response
"records": [ {
"name": "Parent Group",
"description": "Trainee Group",
"system_object": false,
"group_id": "731497821358320"
}],
"_metadata": {
"page": 0,
"records_per_page": 1000,
"page_count": 1,
"total_count": 1
}
}
Unsuccessful response
Scenario 1: The user group name does not exist.
"records": [],
"_metadata": {
"page": 0,
"records_per_page": 1000,
"page_count": 0,
"total_count": 0
}
}
Scenario 2: You search by both the user group name and the description.
"timestamp": "2020-12-31T19:43:11.060242Z",
"code": 2300,
"message": "BAD_REQUEST",
"error": "Only one value for search is supported."
}
Scenario 3: You search with any value other than the valid values for the field parameter.
"timestamp": "2020-12-31T19:43:07.367968Z",
"code": 2300,
"message": "BAD_REQUEST",
"error": "Unsupported search field: group_desc"
}
POST /ims/api/v1/groups/user_mappings
Update users associated with groups
Request URL
Request header
Authorization: Bearer <JWT_token>
Request body
"mappings": [
{
"actions": [
{
"op": "string",
"user_ids": [
"string"
]
}
],
"group_id": "string"
}
]
}
Example request body
"mappings": [
{
"actions": [
{
"op": "add",
"user_ids": [
"628553027974274"
]
}
],
"group_id": "721343778993755"
}
]
}
Parameters
Successful response
"message": "SUCCESS"
}
Unsuccessful response
Scenario 1: You specify a group that does not exist.
"timestamp": "2021-06-14T08:57:27.547266Z",
"code": 2300,
"message": "BAD_REQUEST",
"error": "Some groupIds are missing, please send correct groupIds."
}
Scenario 2: You specify one or more users that do not exist.
"timestamp": "2021-06-14T13:23:44.126419Z",
"code": 2300,
"message": "BAD_REQUEST",
"error": "Some userIds are missing, please send correct userIds."
}
Scenario 3: You do not specify a mandatory field.
"timestamp": "2021-06-14T13:25:38.848751Z",
"code": 2300,
"message": "BAD_REQUEST",
"error": "At least one action with valid payload should be present. Please check the documentation for correct request body."
}