Skip to main content
Gainsight Inc.

User Management API

  1. Last updated
  2. Save as PDF

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:

  • If IsActiveUser is set to true, it sends the welcome email to users.
  • (Default) If the value for IsActiveUser flag is false, it does not send the welcome email to users.
Header
  • 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>

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
  • 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>

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
  • 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>

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
  • 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>

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
UndefinedNameError: reference to undefined name 'FieldName' (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
UndefinedNameError: reference to undefined name 'FieldName' (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
UndefinedNameError: reference to undefined name 'ObjectName' (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
UndefinedNameError: reference to undefined name 'ObjectName' (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.  
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    1. User Management API