Skip to main content
Gainsight Inc.

Data Management APIs

  1. Last updated
  2. Save as PDF 
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.

Overview

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.

Prerequisites

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.

Gainsight API 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 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.

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

Request Method

API Details Description
Request Method GET
Request Params

ic, cl, idd, ihc

Notes:

  • ‘ic’ refers to include children of the object being queried.
  • ‘cl’ refers to the children level to which we need the response.
  • 'idd' is a boolean flag that defines whether the picklist details of the picklist fields are to be included in the response or not.
  • ‘ihc’ is a boolean flag that defines whether we should include hidden columns in the response or not.
Request Endpoint https://<customer-domain>/v1/meta/services/objects/<Object name>/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

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

Request Method

API Details Description
Request Method POST
Request Params

objectNames, includeChilds, childLevels, removeHidden, includeDropDowns

  • objectNames is the list of object names to be queried.
  • includeChilds is a boolean whether to include the child relationships of the objects in query or not.
  • childLevels is the level down from the parent object that is queried.
  • removeHidden is a boolean field to remove the hidden field in the response.
  • includeDropDowns is a boolean flag that defines whether the picklist details of the picklist fields are to be included in the response.
Request Endpoint https://<customer-domain>/v1/meta/services/objects/describe

Sample Request

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

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

Request Method

API Details Description
Request Method GET
Request Params

po, em

  • po stands for parent object marker.
  • em is a boolean field that determines whether to exclude related objects in response or not.
Request Endpoint 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

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

Request Method

API Details Description
Request Method POST
Request Params

parentObject, excludeMappings, sortByLabel, externalUse

  • parentObject refers to the parent object name.
  • excludeMappings is a boolean field that determines to include related objects by lookups, in response.
  • sortByLabel is sorting the object labels in response.
  • externalUse should not be tampered.
Request Endpoint https://<customer-domain>/v1/meta/services/objects/

 Notes:

  • objectNames is the list of object names to be queried.
  • includeChilds is a boolean flag that defines whether to include the child relationships of the objects in the query or not.
  • childLevels is the level down from the parent object that is queried.
  • removeDeleted is a boolean field to remove deleted field in the response.
  • removeHidden is a boolean field to remove the hidden field in the response.
  • sortFieldsByLabel is a boolean field to sort the fields in response by their labels.
  • populatePickListOptions is a boolean flag that defines whethter the picklist details of the picklist fields are to be included in the response or not.
  • honorUserContext, host, useCollectionId, honorCustomLookup, populateAutoSuggestDetails, externalContextcan be left as is.

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

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    This page has no tags.