User Management APIs

Introduction

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.

Notes:

The APIs allow you to create, update, and update the status of up to 50 users.
You cannot create and update Super admin field through User Management APIs.

Authentication

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.

Headers

Key	Value
content-type	application/json
accept	application/json, text/plain, /
accept-language	en-GB,en-US;q=0.9,en;q=0.8
<authentication>	<Access Key>

Throttling 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

API	Rate Limit
external User Management APIs	100 requests per hour / 1000 requests 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'.
Maximum 50 users can be created in a go.
If you pass an SFDC user ID, the API will not identify it and create a new user record with the other fields provided.

Method

POST

Endpoint URL

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:

If the ‘notify’ flag is set to 'true', it sends the welcome email to users.
(Default) If the value for ‘notify’ flag is ‘false’, it does not send the welcome email to users.

IMPORTANT: The value of the query parameter notify can be true or false.

Sample Request Body


{
"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"
     }
}
}

Parameters

Parameter *(mandatory)**	Data Type	Values	Description
Company ID*	String	-	A String value that contains the GSID of a company record. Note: ComanyId is applicable only to external users. CompanyId will be set to null for internal type users.
SFDCUserName*	String	-	A String value that contains the unique and valid email for internal type users. Note: Record will be rejected if the same username already exists.
Email*	String	-	A String value that contains the valid email for internal type users.
FirstName	String	-	A String value that contains the first name of user. Note: If value in the name field is not provided then firstname and lastname values are mandatory.
Last Name	String	-	A String value that contains the last name of user. Note: If value in the name field is not provided then firstname and lastname values are mandatory.
License Type	String	Full, Viewer, Viewer Analytics, Internal Collaborators and External	A String value that contains a valid license type label.
SystemType	String	Internal,External, Guest Partner	A String value that contains a value to define whether the user can be an internal or external user.
IsSuperAdmin	Boolean	-	A Boolean value that, when True, specifies that the user is super admin. Note: By default, a user is created as a non-super admin, if not specified.
Manager	String	-	A String value that contains the GSID of a valid user. Note: Self user assignment is not supported.
Name*	String	-	A String value that contains the name of the user. Note: If value in the name field is not provided then firstname and lastname values are mandatory.
Timezone	String	-	A String value that contains the valid timezone label supported by Gainsight.
Title	String	-	A String value that contains the title of user.
IsActiveUser	Boolean	-	A Boolean value that, when True, specifies that the user is active. Note: By default, user is created as an active user.
Locale	String	-	A String value that contains the valid locale label supported by Gainsight.
permissionBundles	List	-	A List value that contains the name of permission bundles (custom/default).
permissionBundleAction	String	-	A String value that indicates whether to append bundles to the existing bundles or overwrite the existing bundles. Note: Default action is ‘append’.
objectName	String	-	A String value that contains the lookup object name.
multiMatchOption FIRSTMATCH MARKASERROR	String	-	A String value that contains the GSID of the first match between the Lookup JSON and the Lookup object. A String value that contains the system respond with an error when multiple records match the criteria between JSON and the Lookup object.
onNoMatch NULLABLE DEFAULTVALUE ERROR	String	-	(Default) A String value that Inserts null value into the target field on no match. A String value that inserts default value into the target field A String value that contains 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 fields are used as identifiers and are not updatable using this API: SFDCUserName, Gsid, SfdcUserId.

Method

PUT

Endpoint URL

https://<customer domain>/v1/users/services?key=[FieldName]

Note:

FieldName is mandatory.
Maximum 50 users can be created in a go.

IMPORTANT: The value of the query parameter key can be SFDCUserName/Gsid/ SfdcUserId. Passing key is mandatory. Value for the field selected as a key must be provided in the user record of update request body. These fields are non updatable.

Sample Request Body


{
"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.

Parameters

Parameter *(mandatory)**	Data Type	Description
Company ID*	String	A String value that contains the GSID of a company record. Note: ComanyId is applicable only to external users. CompanyId will be set to null for internal type users.
SFDCUserName*	String	A String value that contains a unique and valid email for internal type users. Note: Record will be rejected if the same username already exists.
Gsid*	String	A String value that contains a Gsid of the user. Note: This is a non updatable field and can be used as an upsert key for update operation. This field is mandatory if selected as an upsert key in the query parameter.
SfdcUserId*	String	A String value that contains SfdcUserId of the user. Note: This is a non updatable field and can be used as an upsert key for update operation. This field is mandatory if selected as an upsert key in the query parameter.
Email	String	A String value that contains the valid email for internal type users.
FirstName	String	A String value that contains the first name of user.
Last Name	String	A String value that contains the last name of user.
License Type	String	A String value that contains a valid license type label.
IsSuperAdmin	Boolean	A Boolean value that, when True, specifies that the user is super admin. Note: By default, a user is created as a non-super admin, if not specified.
Manager	String	A String value that contains the GSID of a valid user. Note: Self user assignment is not supported.
Name	String	A String value that contains the name of the user.
Timezone	String	A String value that contains the valid timezone label supported by Gainsight.
Title	String	A String value that contains the title of user.
IsActiveUser	Boolean	A Boolean value that, when True, specifies that the user is active. Note: By default, user is created as an active user.
Locale	String	A String value that contains the valid locale label supported by Gainsight.
permissionBundles	List	A List value that contains the name of permission bundles (custom/default).
permissionBundleAction	String	A String value that indicates whether to append bundles to the existing bundles or overwrite the existing bundles. Note: Default action is ‘append’.
objectName	String	A String value that contains the lookup object name.
multiMatchOption FIRSTMATCH MARKASERROR	String	A String value that contains the GSID of the first match between the Lookup JSON and the Lookup object. A String value that contains the system respond with an error when multiple records match the criteria between JSON and the Lookup object.
onNoMatch NULLABLE DEFAULTVALUE ERROR	String	(Default) A String value that Inserts null value into the target field on no match. A String value that inserts default value into the target field A String value that contains 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": "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

PUT

Endpoint URL

https://<customer domain>/v1/users/services/status?status=true/false

Note: Maximum 50 user statuses can be updated in a go.

IMPORTANT: The value of the query parameter status can be true or false.

Sample Request Body

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"
]

Parameters

Parameter

(*mandatory)

Data Type

Description

gsid*

List of gsid

A List of users whose status need to be updated in bulk.

Sample Success Response


{
"result": true,
"errorCode": null,
"errorDesc": null,
"data": {
     "status": "COMPLETED"
},
"message": null
}

Sample Failure Response


{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "localizedErrorDesc": null,
   "requestId": "5c1d2242-8c71-4c1c-84e3-8f6e9187c650",
   "data": {
       "invalidUserIds": [
           "1P01936XHTA4SF76ZUW5J2RVEZZ8H33C8MAM",
           "1P01936XHTA4SF76ZU5RWZWIMDDL54UB7UF9",
           "1P01936XHTA4SF76ZUUXHOUMVVSFH9YJM15A"
       ]
   },
   "message": null,
   "localizedMessage": 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

POST

Endpoint URL

https://<customer domain>/v1/users/services/list

Sample Request Body

{


"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)"
}
}

Parameters

Parameter *(mandatory)**	Data Type	Description
limit	Number	A Number value that contains a limit of records sent in one API call.
page	Number	A Number value that contains the next set of records based on the limit.
orderBy	Map	A Map value that contains a field name order by ascending or descending order.
select*	List of fields	A List to get the fields from the object.
where	Map	A Map value which is used to filter records and extract only those records that fulfill a specified condition.
Conditions	List	A List of conditions used to filter out the user records.
expression	String	A String value that contains AND/OR operation.

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

Error Code	Error Message	Reason	HTTP Status Code
GU_1101	Oops, something went wrong.	When there are unexpected errors while processing the request.	500
GU_2400	Too many Requests	API Limit exceeded.	429
GU_2401	Bulk user create operation failed	Create API failed to insert all the records.	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 {{FieldName}}	If the target lookup field is not valid. (i.e. the field is not present in target object)	400
GSOBJ_RLS005	ResolveLookupRequest invalid source lookup mapping {{FieldName}}	If the source lookup field is not valid. (i.e. the field is either not present in user object or not a lookup field)	400
GSOBJ_RLS008	ResolveLookupRequest source collectionMaster not found {{ObjectName}}	Collection master is empty or null for user object.	400
GSOBJ_RLS009	ResolveLookupRequest target collectionMaster not found {{ObjectName}}	Collection master is empty or null for provided target object.	400