User Management API
This article explains about the Gainsight User Management REST APIs and its functionality.
Overview
The User Management APIs are organized around REST (Representational State Transfer). Admins can use these APIs to create users, update users, update user status, and fetch user status.
Note: The APIs allow you to create, update, and update the status of up to 50 users.
Pre-requisites
To use these User Management APIs, ensure that you generate Access Token:
- API Authentication: API access is controlled using a unique Access Key. Contact your Gainsight Admin to get an access key of the Gainsight tenant to which you want to send REST API requests. For more information on how to generate or share an access key, refer to the Generate API Access Key article.
Once you get the access key, you must pass the access key as part of the request header “accesskey” for all of your API requests into Gainsight. The Access Key does not expire.
API Limits
The external User Management APIs limit is 100 requests per hour / 1000 requests per day.
The following are the overall recommended API limits in Gainsight (The exact limits can vary based on your package):
- Synchronous API Calls: 100 API calls per min / 50,000 API call per day
- Asynchronous API Calls (Gainsight bulk APIs limit): 10 calls per hour / 100 per day
Note: All of the above API limits are *Fixed window rate limits.
* Fixed window rate limiting restricts the number of API requests at a specific time. For example, a server can have a rate limiting component that implements a fixed window algorithm that only accepts 100 requests per minute. The time-frame is fixed, and it starts at a specific time. For example, the server will only serve 100 requests between 10:00 am, and 10:01 am.
Create Users
This API can be used to create users in Gainsight. You can also add lookups to resolve manager IDs of the users. The following are the mandatory fields to create users based on the user type:
- Internal Users: Email, SFDCUserName, Name (or FirstName and LastName)
- External Users: CompanyID
Notes:
- If Name is not set, it will be populated from FirstName and LastName.
- If SystemType is not set, it will be set to 'Internal'.
- permissionBundles are the permission bundles which are to be assigned to each user after the user creation is completed. Note that this process is asynchronous and may/may not reflect immediately.
- If IsActiveUser is not set, it will be set as 'active'.
Method Details
API Details | Description |
Request Method | POST |
Request Endpoint |
https://<customer domain>/v1/users/services?notify=true/false You can choose to send a welcome email to the created user by providing the value for notify as ‘true or false’. Notes:
|
Header |
|
Sample Request
{ "records": [ { "FirstName": "Test", "LastName": "User", "Name":"Test User", "Email": "test@gs.com", "LicenseType":"Viewer", "SFDCUserName":"test9@gs.com", "CompanyName":"XYZ" }, { "FirstName": "Test", "LastName": "User", "Name":"Test User", "Email": "test@gs.com", "LicenseType":"Viewer", "SFDCUserName":"test10@gs.com", "CompanyName":"XYZ" } ], "lookups": { "CompanyID": { "fields": { "CompanyName": "Name" }, "lookupField": "Gsid", "objectName": "Company", "multiMatchOption": "FIRSTMATCH", "onNoMatch":"ERROR" } } }
Lookup field details:
- fields: These are the fields used to identify matching records in the lookup object.
- objectName: Lookup object name.
- multiMatchOption (Optional):
- FIRSTMATCH: (Default) This option populates GSID of the first match between the Lookup JSON and the Lookup object.
- MARKASERROR: This option lets the system respond with an error when multiple records match the criteria between JSON and the Lookup object.
- onNoMatch (Optional):
- NULLABLE: (Default) Inserts null value into the target field on no match.
- DEFAULTVALUE: Inserts default value into the target field
- ERROR: This option lets the system respond with an error when no records match the criteria between JSON and the Lookup object.
Sample Success Response
{ "result": true, "errorCode": null, "errorDesc": null, "requestId": "c0d61647-d3ce-4785-8bfe-d6dacc5cdf88", "data": { "status": "SUCCESS", "successRowCount": 2, "records": [ { "IsSuperAdmin": false, "Email": "test@gs.com", "CompanyID": null, "Gsid": "1P01DX6HKU2QAQ2F3FBSO042UN34BJSUGWW1", "FirstName": "Test", "SFDCUserName": "test9@gs.com", "SystemType": "1I0054U9FAKXZ0H26HOLPCQ81MF6AUC6FF2X", "Name": "Test User", "LicenseType": "1I003CYFM4Q8T50O0EK4EPT0XX6S7SUXS5JJ", "IsActiveUser": true, "GainsightLicenseEnabled": false, "LastName": "User" }, { "IsSuperAdmin": false, "Email": "test@gs.com", "CompanyID": null, "Gsid": "1P01DX6HKU2QAQ2F3FHQ0E6LOXYTGK8N7U10", "FirstName": "Test", "SFDCUserName": "test10@gs.com", "SystemType": "1I0054U9FAKXZ0H26HOLPCQ81MF6AUC6FF2X", "Name": "Test User", "LicenseType": "1I003CYFM4Q8T50O0EK4EPT0XX6S7SUXS5JJ", "IsActiveUser": true, "GainsightLicenseEnabled": false, "LastName": "User" } ], "errors": [], "success": true }, "message": null }
Sample Failure Response
{ "result": false, "errorCode": "GU_2403", "errorDesc": "Lookup objects [Company1] are not valid", "requestId": "0bf61426-63ad-4774-ad95-4bd2f6c43c25", "data": null, "message": null }
Update Users
This API can be used to update user details in Gainsight. The following are the supported user fields which can be updated using this API: SFDCUserName, Gsid, SfdcUserId.
Method Details
API Details | Description |
Request Method | PUT |
Request Endpoint |
https://<customer domain>/v1/users/services?key=[FieldName] Note: FieldName is mandatory. |
Header |
|
Sample Request
{ "records": [ { "IsActiveUser":true, "LicenseType": "Full", "SFDCUserName": "test3@gs.com", "CompanyName": "XYZ", "permissionBundles":["DEFAULT_BUNDLE"] }, { "LicenseType":"Full", "SFDCUserName":"test2@gs.com", "permissionBundles":["DEFAULT_BUNDLE"], "CompanyName":"XYZ" } ], "lookups": { "CompanyID": { "fields": { "CompanyName": "Name" }, "lookupField": "Gsid", "objectName": "Company", "onNoMatch":"ERROR" } }, "permissionBundleAction":"overwrite" }
PermissionBundleAction:
- permissionBundleAction option indicates whether to append bundles to the existing bundles or overwrite the existing bundles.
- Default action is ‘append’.
- ‘append/overwrite’ are the supported actions.
Sample Success Response
{ "result": true, "errorCode": null, "errorDesc": null, "requestId": "5dd9296a-c5d3-4ae1-8fbb-56fd3a2e4d86", "data": { "status": "SUCCESS", "successRowCount": 2, "records": [ { "Email": "test3@gs.com", "CompanyID": null, "Gsid": "1P01DX6HKU2QAQ2F3F7JU49M384I1MDU66B9", "SystemType": "Internal", "Name": "Test User", "LicenseType": "Full", "IsActiveUser": true, "IsSuperAdmin": false, "FirstName": "Test", "SFDCUserName": "test3@gs.com", "GainsightLicenseEnabled": false, "LastName": "User" }, { "Email": "test2@gs.com", "CompanyID": null, "Gsid": "1P01DX6HKU2QAQ2F3FKTBOET0641B3PBC2TO", "SystemType": "Internal", "Name": "Test User", "LicenseType": "Full", "IsActiveUser": true, "IsSuperAdmin": false, "FirstName": "Test", "SFDCUserName": "test2@gs.com", "GainsightLicenseEnabled": false, "LastName": "User" } ], "errors": [], "success": true }, "message": null }
Sample Failure Response
{ "result": false, "errorCode": "GU_2403", "errorDesc": "Lookup objects [Company1] are not valid", "requestId": "0bf61426-63ad-4774-ad95-4bd2f6c43c25", "data": null, "message": null }
Update Users Status
This API can be used to update the status (active/inactive) of the users in Gainsight.
Method Details
API Details | Description |
Request Method | PUT |
Request Endpoint | https://<customer domain>/v1/users/services/status?status=true/false |
Header |
|
Sample Request
In the request body, you must add the User GSIDs to update the respective users. The API call ignores the invalid User GSIDs, so ensure that you have provided valid User GSIDs in the request.
[ "1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9", "1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A", "1P01936XHTA4SF76ZUW5J2RVEZZ8H33C8MAM" ]
Sample Success Response
{ "result": true, "errorCode": null, "errorDesc": null, "data": { "status": "COMPLETED" }, "message": null }
Fetch User Details
This API can be used to get the details of the users in Gainsight. You can provide the attributes to view the user details in the API response.
Method Details
API Details | Description |
Request Method | POST |
Request Endpoint | https://<customer domain>/v1/users/services/list |
Header |
|
Sample Request
{ "includeTotal": true, "limit": 25, "page": 0, "orderBy": { "ModifiedDate": "desc" }, "select": [ "Name", "SFDCUserName", "Email", "IsSuperAdmin", "ModifiedDate", "LicenseType" ], "where": { "conditions": [ { "name": "SystemType", "alias": "SystemTypeNotIn", "value": [ "1I0054U9FAKXZ0H26H8LWSP9IXL2NBBNBAGG", "1I00BVVU4MEPNLT5UUTEI7IOVQ51BTETMIYR" ], "operator": "NOT_IN" }, { "alias": "A", "name": "SystemType", "operator": "IN", "value": [ "1I0054U9FAKXZ0H26HIODPYB6VXM69JDPA5O", "1I0054U9FAKXZ0H26HR1I0W4KFTTAGJ8UIUH" ] } ], "expression": "SystemTypeNotIn AND (A)" } }
Sample Success Response
{ "result": true, "errorCode": null, "errorDesc": null, "requestId": "873207cc-f7fb-47df-9034-de4797a94ad5", "data": { "page": 0, "size": 5, "total": 5, "limit": 25, "users": [ { "IsSuperAdmin": false, "Email": "test3@gs.com", "Gsid": "1P0186EIDXGJI1O93WM1ZK3A19R6ORXFQTFY", "SFDCUserName": "test3@gs.com", "ModifiedDate": "2021-12-01T11:13:47Z", "ProfilePicture": null, "Name": "Test User", "LicenseType": "Full", "Status": "Active" } ] }, "message": null }
Sample Failure Response
{ "result": false, "errorCode": "GU_1705", "errorDesc": "Invalid select fields", "requestId": "981cdb70-675e-4052-b7a1-9521526892ca", "data": null, "message": null }
Error Codes
Create API failed to insert all the records
Error Codes | Error Description | Reason | HTTP Status Code |
GU_1101 | Oops, something went wrong. | When there are unexpected errors while processing the request. | 500 |
GU_2400 | Too many request | API Limit exceeded | 429 |
GU_2401 | Bulk user create operation failed | ||
400 | |||
GU_2402 | Bulk user update operation failed | Failed to Update all the records | 400 |
GU_2403 | Lookup configuration is invalid | If Invalid lookup configuration provided in create/update user request | 400 |
GU_2404 | Lookup field cannot be null or empty | If either source or target lookup field is null or empty | 400 |
GU_2405 | Lookup Object is not valid | One of the Target object names provided in the lookups is null or empty | 400 |
GU_2406 | Invalid lookup match criteria | If matching criteria in the lookup(s) is empty or null | 400 |
GU_2407 | Fields do not exist in user record | If the field(s) provided in the matching criteria do not present in the user records to be created/updated | 400 |
GU_2409 | Key provided in the request is not supported | Invalid identifier provided in user update request. | 400 |
GU_2410 | Same user cannot be added as a manager | self-manager is not allowed | 400 |
GU_2411 | Conflict in update for the user | If the same user is provided multiple times in the user update request | 400 |
GSOBJ_RLS004 | ResolveLookupRequest invalid target lookup mapping (click for details) Callstack:
at (SFDC_Edition/API_and_Developer_Docs/User_Management_API/User_Management_API), /content/body/div[7]/table/tbody[2]/tr[11]/td[2]/span, line 1, column 1
|
If the target lookup field is not valid. (i.e. the field is not present in target object) | |
GSOBJ_RLS005 | ResolveLookupRequest invalid source lookup mapping (click for details) Callstack:
at (SFDC_Edition/API_and_Developer_Docs/User_Management_API/User_Management_API), /content/body/div[7]/table/tbody[2]/tr[12]/td[2]/span, line 1, column 1
|
If the source lookup field is not valid. (i.e. the field is either not present in user object or not a lookup field) | |
GSOBJ_RLS008 | ResolveLookupRequest source collectionMaster not found (click for details) Callstack:
at (SFDC_Edition/API_and_Developer_Docs/User_Management_API/User_Management_API), /content/body/div[7]/table/tbody[2]/tr[13]/td[2]/span, line 1, column 1
|
Collection master is empty or null for user object. | |
GSOBJ_RLS009 | ResolveLookupRequest target collectionMaster not found (click for details) Callstack:
at (SFDC_Edition/API_and_Developer_Docs/User_Management_API/User_Management_API), /content/body/div[7]/table/tbody[2]/tr[14]/td[2]/span, line 1, column 1
|
Collection master is empty or null for provided target object. |