Skip to main content
Gainsight Inc.

User Management APIs

Gainsight NXT

 

This article explains about the Gainsight User Management REST APIs and its functionality.

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.

Note: 

  • The APIs allow you to create, update, and update the status of up to 50 users.
  • You cannot create and update the Super admin field through User Management APIs.
  • External action in rules does not support the update of the permission bundle for users. To dynamically assign users to a permission bundle, set dynamic rules on user attributes in the permission bundle. This ensures that users who meet the criteria automatically receive the permission bundle based on the defined conditions.

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 -

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 -

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 String value that contains a valid license type label.
SystemType String Internal,External, Guest
Partner
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

String value that contains the first name of user.

Last Name String

String value that contains the last name of user.

License Type String 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
  • Was this article helpful?