Data Management APIs
- Last updated
- 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.
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:
|
Request Endpoint | http://<customer-domain>/v1/meta/services/objects/<Object name>/describe?ic=true&cl=3&idd=true |
Sample Request
http://<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
|
Request Endpoint | http://<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
|
Request Endpoint | http://<customer-domain>/v1/meta/services/objects/list?po=company&em=false |
Sample Request
http://<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
|
Request Endpoint | http://<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" }