Data Management APIs

Last updated
Save as PDF

IMPORTANT - Articles Impacted due to 6.34 October NXT Release

Due to the v6.34 October, 2022 release, this article has been impacted. Steps, images, and playable GIFs in this article will soon be updated to reflect the latest changes.

For more information about the latest UI changes, click here.

Gainsight NXT

This article supports Gainsight NXT, the next evolution of the Customer Success platform. If you are using Gainsight CS Salesforce Edition, you can find supporting documentation by visiting the home page, and selecting CS > Salesforce Edition.

Not sure what your team is using? Click here.

The Data Management APIs are organized around REST (Representational State Transfer). This article explains to Admins the details of how these REST APIs can be used to get Gainsight Object and field details.

Introduction

Gainsight enables Admins to get Object and field metadata information using REST APIs. Not all teams who benefit from accessing Data Management always use Gainsight. They have systems of their choice and expect Gainsight to integrate better with them. Customers who have the development resources can use the APIs to build tighter and more customized integrations between Gainsight and other systems they use.

Business Use Case: When a customer wants to integrate their applications with Gainsight. They would want to understand how their data is going to be stored in Gainsight, that is the structure of metadata in a Gainsight Object. Such customers can use these APIs to get an understanding of the metadata of the Gainsight Object without logging into the Gainsight application.

Authentication

To use these Data 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
Access Key	For more information on how to generate an access key, refer to the Authentication section.
Content Type	JSON

Throttling Limits

The following are the recommended API limits for Gainsight APIs (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 limits restrict 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.

API	Rate Limit
Get Describe OMD	100 API calls per min / 50,000 API call per day
Post Describe OMD	100 API calls per min / 50,000 API call per day
Get Lite API Call OMD	100 API calls per min / 50,000 API call per day
Post Lite API Call OMD	100 API calls per min / 50,000 API call per day

Get Describe OMD

This API fetches the Object details and the related Object details such as ObjectName, label, objectType, labelPlural, and keyPrefix. It also fetches the following information about the Object’s fields:

Filterable
Sortable
Groupable
Createable
updateable
Formulafield
hasLookup
Required
Richtext
Nillable
Readonly
dependentPicklist
fieldGroupType
selfLookup
Indexed
decimalPlaces
Hidden
Namefield
Description
aggregatable

Method

GET

Endpoint URL

https://<customer-domain>/v1/meta/services/objects/<Objectname>/describe?ic=true&cl=3&idd=true

Sample Request

https://<customer-domain>/v1/meta/services/objects/autoindex10__gc/describe?ci=mda&ic=true&cl=3&idd=true

Parameters

Parameters*	Data Type	Description
ic	Boolean	A Boolean flag that refers to include the children of the object being queried.
cl	Number	A Number flag that refers to the children level to which we need the response.
idd	Boolean	A Boolean flag that defines whether the picklist details of the picklist fields are to be included in the response or not.
ihc	Boolean	A Boolean flag that defines whether we should include hidden columns in the response or not.

Sample Success Response

{
    "requestId": "2d9d59b6-f9e2-41ff-90fd-01096b4986d0",
    "result": true,
    "data": [
        {
            "objectName": "autoindex10__gc",
            "label": "AutoIndex10",
            "objectType": "CUSTOM",
            "labelPlural": "AutoIndex10",
            "keyPrefix": "1Z02KRI7NHRRVF6ZWJ",
            "fields": [
                {
                    "fieldName": "CreatedDate",
                    "label": "GS Created Date",
                    "dataType": "DATETIME",
                    "objectName": "autoindex10__gc",
                    "meta": {
                        "properties": {
                            "sourceType": "DATETIME"
                        },
                        "filterable": true,
                        "sortable": true,
                        "groupable": true,
                        "createable": false,
                        "updateable": false,
                        "formulaField": false,
                        "hasLookup": false,
                        "required": false,
                        "richText": false,
                        "nillable": true,
                        "readOnly": true,
                        "dependentPicklist": false,
                        "fieldGroupType": "SYSTEM",
                        "selfLookup": false,
                        "indexed": true,
                        "decimalPlaces": 0,
                        "hidden": false,
                        "nameField": false,
                        "description": "Created Date",
                        "aggregatable": true
                    }
                },
                {
                    "fieldName": "gsArr__gc",
                    "label": "ARR",
                    "dataType": "PERCENTAGE",
                    "objectName": "autoindex10__gc",
                    "meta": { 
                            "properties": {
                            "sourceType": "PERCENTAGE"
                        },
                        "filterable": true,
                        "sortable": true,
                        "groupable": true,
                        "createable": true,
                        "updateable": true,
                        "formulaField": false,
                        "hasLookup": false,
                        "required": false,
                        "richText": false,
                        "nillable": true,
                        "readOnly": false,
                        "dependentPicklist": false,
                        "fieldGroupType": "CUSTOM",
                        "selfLookup": false,
                        "indexed": false,
                        "decimalPlaces": 0,
                        "hidden": false,
                        "nameField": false,
                        "description": "Arr for the company",
                        "aggregatable": true
                    }
                },
                {
                    "fieldName": "Arr",
                    "label": "ARR",
                    "dataType": "CURRENCY",
                    "objectName": "company",
                    "meta": {
                        "properties": {
                            "sourceType": "CURRENCY"
                        },
                        "filterable": true,
                        "sortable": true,
                        "groupable": true,
                        "createable": true,
                        "updateable": true,
                        "formulaField": false,
                        "hasLookup": false,
                        "required": false,
                        "richText": false,
                        "nillable": true,
                        "readOnly": false,
                        "dependentPicklist": false,
                        "fieldGroupType": "STANDARD",
                        "selfLookup": false,
                        "indexed": false,
                        "decimalPlaces": 2,
                        "hidden": false,
                        "nameField": false,
                        "aggregatable": true
                    }
                }
            ],
            "transactional": false,
            "readable": true,
            "createable": true,
            "schemaUpdateable": true
        }
    ]
}

Sample Failure Response

{
"requestId": "b698e142-fa4a-4c38-aa75-7d0cc34f3098",
"result": false,
"instance": "2021-02-03 10:31:28 UTC",
"title": "OBJECT_NOT_FOUND",
"detail": "Requested object not found.",
"errorDesc": "Requested object not found."
}

Post Describe OMD

This API is used to fetch the specific Objects detail and related Objects detail by filtering the response. You get Object details such as ObjectName, label, objectType, labelPlural, and keyPrefix. It also fetches the following information about the Object’s fields:

Filterable
Sortable
Groupable
Createable
updateable
Formulafield
hasLookup
Required
Richtext
Nillable
Readonly
dependentPicklist
fieldGroupType
selfLookup
Indexed
decimalPlaces
Hidden
Namefield
Description
aggregatable

Method

POST

Endpoint URL

https://<customer-domain>/v1/meta/services/objects/describe

Sample Request

{
    "objectNames": [
        "autoindex10__gc"
    ],
    "includeChilds": "true",
    "childLevels": "1",
    "includeDropDowns": "true",
    "useCollectionId": "false",
    "removeHidden": "false",
}

Parameters

Parameters*	Data Type	Description
objectNames	String	A String that has a list of object names to be queried.
includeChilds	Boolean	A Boolean whether to include the child relationships of the objects in the query or not.
childLevels	Number	A Number to level down from the parent object that is queried.
removeHidden	Boolean	A Boolean field to remove the hidden field in the response.
includeDropDowns	Boolean	A Boolean flag that defines whether the picklist details of the picklist fields are to be included in the response.

Sample Success Response

{
    "requestId": "630e7e73-a700-4f76-a2ca-3b0d86ae2434",
    "result": true,
    "data": [
{
    "objectName": "autoindex10__gc",
    "label": "AutoIndex10",
    "objectType": "CUSTOM",
    "labelPlural": "AutoIndex10",
    "keyPrefix": "1Z02KRI7NHRRVF6ZWJ",
     "fields": [
 {
     "fieldName": "CreatedDate",
     "label": "GS Created Date",
     "dataType": "DATETIME",
     "objectName": "autoindex10__gc",
     "meta": {
     "properties": {
     "sourceType": "DATETIME"
 },
     "filterable": true,
     "sortable": true,
     "groupable": true,
     "createable": false,
     "updateable": false,
     "formulaField": false,
     "hasLookup": false,
     "required": false,
     "richText": false,
     "nillable": true,
     "readOnly": true,
     "dependentPicklist": false,
     "fieldGroupType": "SYSTEM",
     "selfLookup": false,
     "indexed": true,
     "decimalPlaces": 0,
     "hidden": false,
     "nameField": false,
     "description": "Created Date",
     "aggregatable": true
 }
 },
 {
     "fieldName": "gsArr__gc",
     "label": "ARR",
     "dataType": "PERCENTAGE",
     "objectName": "autoindex10__gc",
     "meta": {
     "properties": {
     "sourceType": "PERCENTAGE"
 },
     "filterable": true,
     "sortable": true,
     "groupable": true,
     "createable": true,
     "updateable": true,
     "formulaField": false,
     "hasLookup": false,
     "required": false,
     "richText": false,
      "nillable": true,
      "readOnly": false,
      "dependentPicklist": false,
      "fieldGroupType": "CUSTOM",
      "selfLookup": false,
      "indexed": false,
      "decimalPlaces": 0,
      "hidden": false,
      "nameField": false,
      "description": "Arr for the company",
      "aggregatable": true
 }
 },
 {
      "fieldName": "Arr",
         "label": "ARR",
         "dataType": "CURRENCY",
         "objectName": "company",
         "meta": {
         "properties": {
              "sourceType": "CURRENCY"
 },
      "filterable": true,
      "sortable": true,
      "groupable": true,
      "createable": true,
      "updateable": true,
      "formulaField": false,
      "hasLookup": false,
      "required": false,
      "richText": false,
      "nillable": true,
      "readOnly": false,
      "dependentPicklist": false,
      "fieldGroupType": "STANDARD",
      "selfLookup": false,
      "indexed": false,
      "decimalPlaces": 2,
      "hidden": false,
      "nameField": false,
      "aggregatable": true
  }
  }
  ],
     "transactional": false,
     "readable": true,
     "createable": true,
     "schemaUpdateable": true
 }
 ]
 }

Sample Failure Response

{
"requestId": "b698e142-fa4a-4c38-aa75-7d0cc34f3098",
"result": false,
"instance": "2021-02-03 10:31:28 UTC",
"title": "OBJECT_NOT_FOUND",
"detail": "Requested object not found.",
"errorDesc": "Requested object not found."
}

Get Lite API Call OMD

This API is used to fetch the list of Objects with the minimum metadata information such as:

objectName
Label
objectType
keyPrefix
Transactional
multiCurrencySupported
Readable
Createable
schemaUpdateable

Method

GET

Endpoint URL

https://<customer-domain>/v1/meta/services/objects/list?po=company&em=false

Sample Request

https://<customer-domain>/v1/meta/services/objects/list?po=company&em=false

Parameters

Parameters*	Data Type	Description
po	String	A String value that stands for parent object marker.
em	Boolean	A Boolean field that determines whether to exclude related objects in response or not.

Sample Success Response

{
"requestId": "7ac6a2e6-85ac-44df-958a-ee4b00384436",
"result": true,
"data": [
     {
         "objectName": "autoindex10__gc",
         "label": "AutoIndex10",
         "objectType": "CUSTOM",
         "keyPrefix": "1Z02KRI7NHRRVF6ZWJ",
         "transactional": true,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "company",
         "label": "Company",
         "objectType": "STANDARD",
         "keyPrefix": "1P02C503CKNHR9B14K",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "company_person",
         "label": "Company Person",
         "objectType": "STANDARD",
         "keyPrefix": "1C01TEHFH1FP2KG5WQ",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "email_logs",
         "label": "Email Logs",
         "objectType": "STANDARD",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "email_raw_events",
         "label": "Email Raw Events",
         "objectType": "SYSTEM",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": false,
         "schemaUpdateable": false
     },
     {
         "objectName": "obj1__gc",
         "label": "Obj1",
         "objectType": "CUSTOM",
         "keyPrefix": "1Z024OYZBEOENYQ9RH",
         "transactional": true,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "relationship",
         "label": "Relationship",
         "objectType": "STANDARD",
         "keyPrefix": "1P05VX75GX1CCNZ59W",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "relationship_person",
         "label": "Relationship Person",
         "objectType": "STANDARD",
         "keyPrefix": "1C03FQDZ4TJLWHYROF",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "sponsor_tracking",
         "label": "Sponsor Tracking",
         "objectType": "STANDARD",
         "keyPrefix": "1S075PAB66AVNGO818Y",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": false,
         "schemaUpdateable": true
     },
     {
         "objectName": "gsuser",
         "label": "User",
         "objectType": "STANDARD",
         "keyPrefix": "1P01N68IASVWNJD6IE",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": true,
         "schemaUpdateable": true
     },
     {
         "objectName": "user_shared_detail",
         "label": "User Shared Detail",
         "objectType": "STANDARD",
         "keyPrefix": "P02",
         "transactional": false,
         "multiCurrencySupported": false,
         "readable": true,
         "createable": false,
         "schemaUpdateable": true
     }
]
}

Sample Failure Response

{
"requestId": "7007e23f-e5c7-4381-995a-86cba5635c19",
"result": false,
"instance": "2021-02-03 10:32:50 UTC",
"title": "PARENT_OBJECT_NOT_FOUND",
"detail": "Parent Object Not Found or Invalid Object",
"errorDesc": "Parent Object Not Found or Invalid Object"
}

Post Lite API Call OMD

This API is used to fetch the specific list of Objects with the minimum metadata information by filtering the required Objects. It gets Object details such as:

objectName
label
objectType
keyPrefix
Transactional
multiCurrencySupported
Readable
Createable
schemaUpdateable

Method

POST

Endpoint URL

https://<customer-domain>/v1/meta/services/objects/

Sample Request

{
    "externalUse":"true",
    "parentObject":"company",
    "excludeMappings":"false",
    "sortByLabel":"false"
}

Sample Success Response

{
    "requestId": "ec934e17-5420-4221-80fc-97655e8e750b",
    "result": true,
    "data": [
        {
            "objectName": "anonymous_person",
            "label": "Anonymous Person",
            "objectType": "STANDARD",
            "keyPrefix": "1C02M7XRJCBG6QI6SV",
            "transactional": false,
            "multiCurrencySupported": false,
            "readable": true,
            "createable": true,
            "schemaUpdateable": true
        },
        {
            "objectName": "user_shared_detail",
            "label": "User Shared Detail",
            "objectType": "STANDARD",
            "keyPrefix": "P02",
            "transactional": false,
            "multiCurrencySupported": false,
            "readable": true,
            "createable": false,
            "schemaUpdateable": true
        }
    ]
}

Sample Failure Response

{
"requestId": "7007e23f-e5c7-4381-995a-86cba5635c19",
"result": false,
"instance": "2021-02-03 10:32:50 UTC",
"title": "PARENT_OBJECT_NOT_FOUND",
"detail": "Parent Object Not Found or Invalid Object",
"errorDesc": "Parent Object Not Found or Invalid Object"
}