Gainsight Custom Object API Documentation

Introduction

This document provides details of REST APIs that can be used for creating, updating, reading, and deleting records in the Low Volume custom objects created in the Gainsight’s Data Management.

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.

Prerequisites

To use APIs in this document, make sure that required sub-domain or custom domain is created, Example: https://customobjectapi.gainsightcloud.com or https://customobjectapi .yourcompany.com. For more information on how to create a domain, refer Setup a Gainsight Domain.

You can add your domain in the Endpoint URL to connect to Gainsight.
To use these custom object APIs, ensure that necessary Low Volume custom objects are created in your Gainsight org.

Low Volume custom object can be created as shown below:

Navigate to the Administration > Data Management page.
Click +OBJECT to create a custom object.
Select Low Volume Object to create Low Volume custom objects.

Create Low Volume Object.png

Pass field names as Keys that are as captured from the Data Management schema as shown below:

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. To generate or share an access key, Gainsight Admin can refer the article Generate API Access Key.

Once you get your access key, you will have to pass as part of the request header “accesskey” for all of your API requests into Gainsight. The AccessKey does not expire.

Insert API

Insert API is used to insert one or more records into the Gainsight custom object. You can insert a maximum of 50 records per API call. If you want to perform bulk loading (inserting more than 50 records), you can use Gainsight S3 Connector or Gainsight Bulk API.

This API validates all fields in an object before inserting the records. If the validation is successful, the records are inserted into the object. If the validation fails for any record on any field, then the API call fails with a validation error.

Method Details

HTTP Method	POST
Content Type	application/json
Response Format	JSON
Requires Authentication	Yes
Header	Accesskey

Required Parameters	How To Use	Description
API Key	Passed through the Request Header	Pass the API Access key you received from Gainsight in the header “Accesskey”
New Record JSON	Passed through the Request Body	This is the JSON that represents a new record that you create. A sample JSON is shown in the below section Request Body.

Endpoint URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}

In the Endpoint URL:

https://customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is just for reference only.
Object name is the name of the custom object in Gainsight. For example, this Object, this Usecase, etc. Actual endpoint URL will look like ........gainsightcloud.com/v1/data/objects/thisObject__gc.

Object names used above are just for reference only. You can create an object with the name as per your requirement and use case. You can confirm the correct object name that should be passed through endpoint URL from the page Administration > Data Management.

Request Body

Pass the records that you want to insert into the object in the request body. Fields in the object and their associated values are passed as key value pairs as shown below. Pass each record that needs to be inserted as an array item. You can insert a maximum of 50 records through an API call.

You can pass Date and DateTime values in the API in one of the supported formats listed in the article Gainsight Data Management.

Following is the sample JSON to insert records into the custom object:

{
  "records": [
    {
      "CSMLastName": "Johnson",
      "CSMFirstName": "Paul",
      "Name": "Gainsight, Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 23,
      "Employees": 12
    },
    {
      "CSMLastName": "Sharma",
      "CSMFirstName": "Rohan",
      "Name": "Verizon",
      "Stage": "New Customer",
      "LifecycleInWeeks": 13,
      "Employees": 22
    },
    {
      "CSMLastName": "Mendis",
      "CSMFirstName": "Jeevan",
      "Name": "ABC Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 31,
      "Employees": 889
    },
    {
      "CSMLastName": "Srivastava",
      "CSMFirstName": "Avneesh",
      "LifecycleInWeeks": 9,
      "Employees": 290,
      "Name": "ACME Corp."
    },
    {
      "CSMLastName": "Singh",
      "CSMFirstName": "Sandeep",
      "LifecycleInWeeks": 19,
      "Employees": 89,
      "Name": "XYZ Inc."
    }
  ],
  "lookups": {
    "CSM": {
      "fields": {
        "CSMFirstName": "FirstName",
        "CSMLastName": "LastName"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    }
  }
}

Import Lookup

You can pass Import lookup configuration as part of the request body. Import lookup configuration allows you to populate GSID’s into a field by referencing it from another object in Gainsight. Ensure that you pass the fields of GSID type to populate GSID from another object. One JSON applies for Lookups to all the records that are inserted to populate field of GSID data type.

{
  "lookups": {
    "CSM": {
      "fields": {
        "CSMFirstName": "FirstName",
        "CSMLastName": "LastName"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    }
  }
}

In the above Lookups code snippet, keys are defined as below:

“CSMFirstNAME” (in request body): “FirstName” (field name in the GS User object to match)
“CSMLastName” (in request body): “LastName” (field name in the GS User object to match)

Note: You can pass multiple fields from the source to match with the multiple lookup fields (Ex: GS User object > Fields) to find the right match.
“lookupField”: “Gsid” (lookup field name), Ex: GS User > GSID
“objectName” : “gsuser” (lookup object name), Ex: GS User.

There are two options supported for the key multiMatchOption:

FIRSTMATCH: (Default) This option populates GSID of the first match between the Lookup JSON and the GS User object.
MARKASERROR: This option lets the system responds with an error when multiple records match the criteria between JSON and the GS User object.

There are three options supported for the key onNoMatch:

NULLABLE: (Default) Selecting this option inserts null value into the target field.
DEFAULTVALUE: Selecting this option inserts default value into the target field.

Note: You can assign a default value to a field in the page Administration > Data Management > [Select the target object] > [Edit the target field]
ERROR: This option lets the system responds with an error when no records match the criteria between JSON and the GS User object.

For example, in the below code snippet, CSM field is populated with GSID from the GS User object by matching CSMFirstName (in request body) with FirstName (in GSuser) and CSMLastName (in request body) with LastName (in GSuser).

Direct Import Lookup_CustomObject.png

Success Response

Successful API request will return HTTP status code 200 as response. Format of the response is as shown below. Success response contains the list of all records that have been successfully inserted. A sample Success Response is shown below:

Response for each record includes the unique GSID created for the record and the actual values of the fields in the inserted record.
Below response also shows that the CSM field for each record is successfully populated with GSID from the GS User object. This value is populated through the Import Lookup Configuration in the JSON Request body.
Date and DateTime values are shown in epoch format.
Dropdown list items like Stage and Status are populated with a unique GSID of an item.

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
  "data": {
    "records": [
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "Gainsight, Inc.",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1562691459623,
        "Gsid": "1P02MRXML1GRDV44YOYPEBMABN5JYVTAATP8",
        "LifecycleInWeeks": 23,
        "Employees": 12
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "Verizon",
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO6NO2DQXRNTQYQXDLGF",
        "LifecycleInWeeks": 13,
        "Employees": 22
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "CreatedDate": 1521691459693,
        "Name": "ABC Inc.",
        "Status": "8K2274U9FAKXZ0H26HO92M3F1G5SPWVQXYS8",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YOL2PI8HX2NJRH5NQTEE",
        "LifecycleInWeeks": 31,
        "Employees": 889
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "CreatedDate": 1521691459693,
        "Name": "ACME Corp.",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "LifecycleInWeeks": 9,
        "Employees": 290
      },
      {
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "CreatedDate": 1521691459693,
        "Name": "XYZ Inc.",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO87PCQFV0QIRSDZZ3DN",
        "LifecycleInWeeks": 19,
        "Employees": 89
      }
    ]
  },
  "message": null
}

Error Response

If your API request results in an error, an error response is returned in the following format. The error response has a Gainsight error code and error description. Gainsight error code and HTTP status code responses can be due to various reasons. For the full list of Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer Error Codes for Company and Custom Object APIs.

When you make an API call, parsing is stopped at the field on the first validation failure. Hence, you receive an error response with validation errors for the first failed field. “Data” key of the response contains additional details on the failure reasons. If the validation is successful on all of the fields, then the records are inserted into the object.

In the sample error response shown below, API call is failed because of a data validation error while inserting a value in the field “DateTime__gc”.

{
  "result": false,
  "errorCode": "GSOBJ_1005",
  "errorDesc": "Invalid dateTime format (DateTime__gc = XYZ Inc.).",
  "requestId": "39f58495-8f05-4344-8542-ca44ac9afeb8",
  "data": {
    "count": 0,
    "errors": [
      [
        {
          "success": false,
          "parsedValue": "XYZ Inc.",
          "errors": [
            {
              "errorMessage": "Invalid dateTime format",
              "errorCode": "GSOBJ_1005",
              "fieldName": "DateTime__gc",
              "invalidValue": "XYZ Inc."
            }
          ]
        }
      ]
    ],
    "records": null
  },
  "message": null
}

Update API

Update API is used to update one or more existing records in a custom object. Existing records are identified using the keys specified in the Endpoint URL and values in the remaining fields are updated as mentioned in the API call. You can update a maximum of 50 records per API call.

Method Details

HTTP Method	PUT
Content Type	application/json
Response Format	JSON
Requires Authentication	Yes
Header	Accesskey

Required Parameters	How To Use	Description
API Key	Passed through the Request Header	Pass the API Access key you received from Gainsight in the header “Accesskey”
Keys	Passed in the Endpoint URL	Field(s) in the object whose values will be used to identify the record that needs to be updated. You can pass the Keys of data types String, GSID, Number, and Email only.
Update Record JSON	Passed through the Request Body	This is the JSON that represents to identify and update the existing record. A sample JSON is shown in the below section Request Body.

Endpoint URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}?keys={fieldName1,fieldName2}

In the above endpoint URL, https://customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is just for reference only.

If the object name is this Object and the keys are Employees and Industry, a valid endpoint URL to update record(s) in a custom object will look like .........gainsightcloud.com/v1/data/objects/thisObject__gc?keys=Employees,Industry.

Object name and the keys (field names) used above are just for reference only. You can create an object with the name as per your requirement and use case.

Conditions:

Endpoint URL allows you to provide keys of data types String, GSID, Number, and Email only.
You can enter a maximum of 3 keys in the endpoint URL to identify the specific records.
Operator between the keys is always AND, that means records that match the criteria of all the keys will be updated using Update API.

Request Body

Pass the records that you want to update in the object through the request body. Fields in the object and their associated values are passed as key value pairs as shown below. Values in the keys (mentioned in the endpoint URL) are taken as reference to identify the specific records and the remaining fields are updated as specified in the JSON. Pass each record that needs to be updated as an array item. You can update a maximum of 50 records through an API call. Fields of all the data types in an object can be updated through method.

You cannot update values in the fields that are used as keys in the Endpoint URL. To update these fields, you can pass another Update API call with different fields as keys.

You can pass Date and DateTime values in the API in one of the supported formats listed in the article Gainsight Data Management.

Following is the sample Update API call. It has “Name” and “Employees” as keys to identify the specific records that need update, and values in the remaining fields are updated as per JSON for each record. Import lookup configuration to update values in the GSID type fields are passed as explained in the section Import Lookup.

{
  "records": [
    {
      "CSMLastName": "Lee",
      "CSMFirstName": "Shaun",
      "Name": "Gainsight, Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 23,
      "Employees": 12
    },
    {
      "CSMLastName": "Nyumbu",
      "CSMFirstName": "John",
      "Name": "Verizon",
      "Stage": "Launched",
      "LifecycleInWeeks": 13,
      "Employees": 22
    },
    {
      "CSMLastName": "Farbrace",
      "CSMFirstName": "Paul",
      "Name": "ABC Inc.",
      "Status": "Active",
      "LifecycleInWeeks": 31,
      "Employees": 889
    },
    {
      "CSMLastName": "Wasikowska",
      "CSMFirstName": "Mitchelle",
      "LifecycleInWeeks": 9,
      "Employees": 290,
      "Name": "ACME Corp."
    },
    {
      "CSMLastName": "Sharma",
      "CSMFirstName": "Deepak",
      "LifecycleInWeeks": 19,
      "Employees": 290,
      "Name": "XYZ Inc."
    }
  ],
  "lookups": {
    "CSM": {
      "fields": {
        "CSMFirstName": "FirstName",
        "CSMLastName": "LastName"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    }
  }
}

Success Response

Successful API request will return HTTP status code 200 as response. Format of the response is as shown below. Success response contains the list of all records that have been successfully updated.

Response includes the unique GSID and actual values of the fields in the updated record.

A sample Success Response is shown below:

Response for each record includes the unique GSID of the record and the actual values of the fields in the updated record.
Below response also shows that the CSM and Parent Company fields populated with GSIDs from the GS User and Company objects respectively. These values are populated through the Import Lookup Configuration in the JSON Request body.
Date and DateTime values are shown in epoch format.
Dropdown list items like Stage and Status values are populated with unique GSID of an item.

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
  "data": {
    "count": 2,
    "errors": null,
    "records": [
      {
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "Trend": null,
        "Employees": 12,
        "LifecycleInWeeks": 23,
        "OriginalContractDate": 1521743018667,
        "Users": null,
        "gsd36499": null,
        "Shri_Shri_Id__gc": null,
        "ModifiedDate": 1521743018667,
        "ScorecardId": null,
        "Name": "Gainsight, Inc.",
        "Industry": null,
        "RenewalDate": 1521743018667,
        "CurrentScore": null,
        "PreviousScore": null,
        "Parent_Company__gc": null,
        "CreatedDate": 1521691459694,
        "Stage": null,
        "CustomerLifetimeInMonths": 5,
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW"
      },
      {
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Gsid": "1P02MRXML1GRDV44YODC75YNFKEJ4M1CHDR8",
        "Trend": null,
        "Employees": 22,
        "LifecycleInWeeks": 13,
        "OriginalContractDate": 1521743018667,
        "Users": null,
        "gsd36499": null,
        "Shri_Shri_Id__gc": null,
        "ModifiedDate": 1521743018667,
        "ScorecardId": null,
        "Name": "Verizon",
        "Industry": null,
        "RenewalDate": 1521743018667,
        "CurrentScore": null,
        "PreviousScore": null,
        "Parent_Company__gc": null,
        "CreatedDate": 1521691459694,
        "Stage": "1P02MRXML1GRDV44YODC75YNFKEJ4M1CHDR8",
        "CustomerLifetimeInMonths": 2,
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW"
      }
    ]
  },
  "message": null
}

Error Response

If your API request results in an error, an error response is returned in the following format. The error response has a Gainsight error code and error description. Gainsight error code and HTTP status code responses can be due to various reasons. For the full list of Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer Error Codes for Company and Custom Object APIs.

When you make an API call, parsing is stopped at the field on the first validation failure. Hence you receive an error response with validation errors for the first failed field. “Data” key of the response contains additional details on the failure reasons. If the validation is successful on all the fields then the records are updated in the object.

Below error response shows that the Update API is failed because value in the field “Original Contract Date” had an Invalid datetime format.

{
  "result": false,
  "errorCode": "GSOBJ_1006",
  "errorDesc": "Invalid dateTime format (OriginalContractDate = 7809).",
  "requestId": "7cba3c98-b04b-4e21-9e57-44807fa52b8a",
  "data": {
    "count": 0,
    "errors": [
      [
        {
          "success": false,
          "parsedValue": 7809,
          "errors": [
            {
              "errorMessage": "Invalid dateTime format",
              "errorCode": "GSOBJ_1006",
              "fieldName": "OriginalContractDate",
              "invalidValue": 7809
            }
          ]
        }
      ]
    ],
    "records": null
  },
  "message": null
}

Read API

Read API allows you to read one or more records that match a specific criteria from the Gainsight custom object. Read API fetches a maximum of 5000 records from one API call.

If you think there are more than 5000 records that can be fetched, pass another API call with Offset as 5001 so that remaining records (maximum 5000 records again) are fetched. For more information on the Offset, refer the section Read API Request Body.

HTTP Method	POST
Content Type	application/json
Response Format	JSON
Requires Authentication	Yes
Header	Accesskey

Required Parameters	How To Use	Description
API Key	Passed through the Request Header	Pass the API Access key you received from Gainsight in the header “Accesskey”
Read Record JSON	Passed through the Request Body	This is the JSON that represents the entire query criteria. A sample JSON is shown in the section Request Body.

Endpoint URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/query/{objectName}

In this endpoint URL:

https://customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is just for reference only.
Object name is the name of the custom object in Gainsight, e.g. this Object, this Usecase, etc. Actual Endpoint URL with the custom object looks like ......gainsightcloud.com/v1/data/objects/query/thisObject__gc.

Note: Object names used above are just for reference only. You can create an object with the name as per your requirement and use case.

Request Body

You can specify the following elements in the request body of the Read API:

Fields that should be returned
“Where”: conditions to return only records that match a specific criteria
“Operator”: for value in each field, ex: EQ: Equals, CONTAINS, GREATER THAN, etc. Refer the table below for the list of operators supported for each data type.
“Expression”: Operator between the fields to be returned, ex: A OR B, A AND B, etc.
“Order by”: clause to specify the order in which the records should be returned, ascending (asc) or descending (desc).
“Limit”: Max number of records that should be returned
“Offset”: You can enter a record number from which the remaining records (that are in ascending or descending order) are fetched. Ex: If the number of records that match the criteria is 60, If you enter Offset as 10, records from 10 thru 60 are fetched.

Following are the operators supported for the respective fields of data types:

Data Type	Supported Operators
String	equals, not equals, greater or equal, greater than, less or equal, less than, starts with, contains, does not contain, is null, is not null, ends with
Boolean	equals, not equals
Date	equals, not equals, greater or equal, greater than, less or equal, less than, between, is null, is not null
DateTime	equals, not equals, greater or equal, greater than, less or equal, less than, between, is null, is not null
Number	equals, not equals, greater or equal, greater than, less or equal, less than, in, not in, is null, is not null
GSID	equals, not equals, greater or equal, greater than, less or equal, less than, starts with, contains, does not contain, is null, is not null, ends with
Email	equals, not equals, greater or equal, greater than, less or equal, less than, starts with, contains, does not contain, is null, is not null, ends with
Dropdown List	equals, not equals, includes, excludes, starts with, contains, does not contain, is null, is not null
Multi select dropdown list	Includes, excludes, is null, is not null
Currency	equals, not equals, greater or equal, greater than, less or equal, less than, is null, is not null
Percentage	equals, not equals, greater or equal, greater than, less or equal, less than, is null, is not null

Following table lists down the enum operators for each operator supported in Read API:

Operator	Enum Operator
EQ	equals
NE	not equals
LT	less than
GT	greater than
LTE	less or equal
GTE	greater or equal
BTW	between
IS_NULL	is null
IS_NOT_NULL	is not null
CONTAINS	contains
DOES_NOT_CONTAINS	does not contain
STARTS_WITH	starts with
ENDS_WITH	ends with
INCLUDES / IN	includes
EXCLUDES / NOT_IN	excludes

A sample Read API:

{
  "select": [
    "Company_Name__gc",
    "Company_ID__gr.csm__gr.name"
  ],
  "where": {
    "conditions": [
      {
        "name": "Company_Name__gc",
        "alias": "A",
        "value": [
          "Gainsight"
        ],
        "operator": "EQ"
      },
      {
        "name": "Company_ID__gr.csm__gr.name",
        "alias": "B",
        "value": [
          "John"
        ],
        "operator": "CONTAINS"
      }
    ],
    "expression": "A AND B"
  },
  "orderBy": {
    "Company_Name__gc": "asc",
    "Company_ID__gr.csm__gr.name": "desc"
  },
  "limit": 100,
  "offset": 0
}

You can use lookup fields in the Read API to fetch values from another object (not base object). In the above sample API, a lookup field Company_ID__gr.csm__gr.name is used. This field has lookup from base object (ex: thisObject) > Company object > User object (via csm field in Company) > name (field in the User object). From the given field, name is fetched from the User object using lookups.

Note: You cannot filter records with the clause “Group by” using the Read API.

Another sample Read API with different operators:

{
  "select": [
    "Renewal_Date__gc",
    "Company_ID__gr.stage"
  ],
  "where": {
    "conditions": [
      {
        "name": "Renewal_Date__gc",
        "alias": "A",
        "value": [
          "2018-04-01",
          "2018-04-23"
        ],
        "operator": "BTW"
      },
      {
        "name": "Company_ID__gr.stage",
        "alias": "B",
        "value": [
          "New Customer",
          "Kicked Off",
          "Launched"
        ],
        "operator": "IN"
      }
    ],
    "expression": "A OR B"
  },
  "orderBy": {
    "Renewal_Date__gc": "asc",
    "Company_ID__gr.stage": "desc"
  },
  "limit": 100,
  "offset": 0
}

In the above sample API, “where” conditions used are:

Field: Renewal Date / Values: 2018-04-01, 2018-04-23 / Operator: BTW. In this condition, records that have Renewal Date between the two values provided are fetched. When you use the operator BTW, provide two values to fetch the records to match the criteria.
Field: Company_ID__gr.stage / Values: New Customer, Kicked off, Launched / Operator: IN. In this condition, field provided has lookup from the base object to the Company object > Stage field. Records that have company stage as New Customer or Kicked off or Launched are fetched. When you use the operator IN, you can provide one or multiple values to match the criteria.

You can pass Date and DateTime values in the API in one of the supported formats listed in the article Gainsight Data Management.

Success Response

Successful API request will return HTTP status code 200 as response. Format of the success response is as shown below. Fields mentioned in the “Select” section of the API request body will be returned for all the records matching the query criteria.

Following is the sample Success Response for the first sample Read API:

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": [
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "John Nyumbu"
    },
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "John Smith"
    },
    {
      "Company_Name__gc": "Gainsight",
      "Company_ID__gr.csm__gr.name": "Paul Johnson"
    }
  ],
  "message": null
}

Notes: In the Success Response:

Date and DateTime values are shown in epoch format.
Dropdown list items like Stage and Status values are populated with unique GSID of an item.

Error Response

If your API request results in an error, an error response is returned in the following format. The error response has a Gainsight error code and error description. Gainsight error code and HTTP status code responses can be due to various reasons. For the full list of Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer Error Codes for Company and Custom Object APIs.

In the following error response body, error description shows the reason for failure of the Read API.

{
  "result": false,
  "errorCode": "GSOBJ_1XXX",
  "errorDesc": "No data found for given criteria",
  "requestId": "58222b97-eaf0-402e-854d-1914987c4b49",
  "data": null,
  "message": null
}

Delete API

Delete API deletes a specific record in a custom object. Record to be deleted is identified by its GSID, which is passed in the Endpoint URL.

Method Details

HTTP Method	DELETE
Content Type	application/json
Response Format	JSON
Requires Authentication	Yes
Header	Accesskey

Required Parameters	How To Use	Description
API Key	Passed through the Request Header	Pass the API Access key you received from Gainsight in the header “Accesskey”
GSID	Passed in the Endpoint URL	GSID of the record that needs to be deleted

Endpoint URL

https://customobjectapi.gainsightcloud.com/v1/data/objects/{objectName}/{GSID}

In this Endpoint URL, https://customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is just for reference only.

Object name is the name of the object in Gainsight. For example, this Object, this Usecase, etc. GSID is the unique ID of an existing record in the custom object, for example, 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ

Actual Delete Endpoint URL may look like this ......gainsightcloud.com/v1/data/objects/thisObject__gc/1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ

Object names used above are just for reference only. You can create an object with the name as per your requirement and use case.

Success Response

Successful API request will return back HTTP status code 200 as response. Format of the success response is as shown below. GSID of the deleted record is mentioned in the data field of the response.

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": "Record with GSID: 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ successfully deleted.",
  "message": null
}

Error Response

If your API request results in an error, an error response is returned in the following format. The error response has a Gainsight error code and error description. Gainsight error code and HTTP status code responses can be due to various reasons. For the full list of Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer Error Codes for Company and Custom Object APIs.

In the following error response body, error description shows the reason for failure of the Delete API.

{
  "result": false,
  "errorCode": "GSOBJ_1XXX",
  "errorDesc": "No data found for given criteria",
  "requestId": "58222b97-eaf0-402e-854d-1914987c4b49",
  "data": null,
  "message": null
}

Introduction

Gainsight API Limits

​Prerequisites

API Authentication

Insert API

Method Details

Endpoint URL

Request Body

Import Lookup

Success Response

Error Response

Update API

Method Details

Endpoint URL

Request Body

Success Response

Error Response

Read API

Endpoint URL

Request Body

Success Response

Error Response

Delete API

Method Details

Endpoint URL

Success Response

Error Response

Prerequisites