Introduction

The custom object REST APIs help you create, update, read, and delete records in Low Volume custom objects created in Gainsight's Data Management.

Prerequisites

To use APIs in this document, make sure that required sub-domain or custom domain is created. Example: customobjectapi.gainsightcloud.com or customobjectapi.yourcompany.com. For more information on how to create a domain, refer to the Setup a Gainsight Domain article.
Add your domain in the Endpoint URL to connect to Gainsight.
Ensure that necessary Low Volume custom objects are created in your Gainsight org. For more information on how to create Low Volume Custom Objects, refer to the Low Volume Custom Objects section of the Gainsight Objects article.
Pass field names as Keys that are as captured from the Data Management schema.

To use these Company object APIs, ensure that:
1. Company object is installed in your tenant.
2. Required custom fields are created in the Company object.
  To create custom fields in the Company object, navigate to the Administration > Data Management > [Select Company object] page.
Pass field names as Keys that are as captured from the Data Management schema as shown below:

Data Management.jpg

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 your access key, you are required to pass it as part of the request header Accesskey for all of your API requests into Gainsight.

Note: The AccessKey does not expire.

Headers

Key	Value
Accesskey	For more information on how to generate an access key, refer to the Authentication section of this article.
Content Type	JSON

Throttling Limits

API	Rate Limit
Synchronous API Calls	100 API calls per min / 50,000 API call per day
Asynchronous API Calls	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.

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 the Gainsight S3 Connector or Gainsight Bulk API. For more information on the S3 Connector of Bulk API, refer to the Gainsight S3 Connector and Gainsight Bulk API articles respectively.

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

POST

Endpoint URL

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

In the Endpoint URL:

customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is for reference only.
Object name is the name of the custom object in Gainsight. The actual endpoint URL might look something like ...gainsightcloud.com/v1/data/objects/thisObject__gc.

Object names used above are 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 the endpoint URL from the Data Management page.

Sample 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. For more information on the supported formats, refer to the Gainsight Data Management article.

{
  "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__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }
}

Parameters

Parameter (*mandatory)	Data type	Values	Description
records	JSON Array	-	A JSON Array that contains the list of records to be inserted into the object as data. Each JSON key is the field name of the Custom Object created. If any mandatory fields are present in the object, they should be passed in the records fields along with other fields.
lookups	JSON	-	A JSON value that contains the lookup details in case data from other objects are required to populate during the insert activity.

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__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }

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), Example: GS User > GSID
objectName : gsuser (lookup object name), Example: 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).

Sample 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.

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
}

Sample Failure 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 more information on Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer to the Error Codes for Company and Custom Object APIs article.

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. The data key of the response contains additional details on the failure reasons. If the validation is successful on all of the fields, the records are inserted into the object.

The following lists a sample response where the API call 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

The 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

PUT

Endpoint URL

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

In the above endpoint URL, customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is 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 would look something like ...gainsightcloud.com/v1/data/objects/thisObject__gc?keys=Employees,Industry.

Object name and the keys (field names) used above are 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 three 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.

Sample 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. For more information on the supported formats, refer to the Gainsight Data Management article.

Following is the sample Update API call. It has Name and Employees as keys to identify the specific records that need updating, and values in the remaining fields are updated as per JSON for each record. For more information on how to update values in the GSID type fields, refer to the Import Lookup section.

{
  "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__gc": {
            "isLookup": true,
            "fields": {
                "CSM_firstName__gc": "FirstName",
                "CSM_lastName__gc": "LastName"
            },
            "objectName": "gsuser",
            "onNoMatch": "NULLABLE",
            "multiMatchOption": "FIRSTMATCH",
            "lookupField": "Gsid"
        }
    }
}

Parameters

Parameter (*mandatory)	Data type	Values	Description
records	JSON Array	-	A JSON Array that contains the list of records to be inserted into the object as data. Each JSON key is the field name of the Custom Object being created.
lookups	JSON	-	A JSON value that contains the lookup details in case data from other objects are required to populate during the update activity.

Sample Success Response

A Successful API request returns HTTP status code 200 as response. The success response contains the list of all records that have been successfully updated. It 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 a 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
}

Sample Failure 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 more information on Gainsight error codes, error descriptions, their reasons, and HTTP status codes, refer to the Error Codes for Company and Custom Object APIs article.

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.

The following lists a sample response where the API failed because the value in the Original Contract Date field 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

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

Note: 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 to the section Read API Request Body section of this article.

Method

POST

Endpoint URL

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

In the endpoint URL:

customobjectapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is for reference only.
Object name is the name of the custom object in Gainsight. The actual Endpoint URL with the custom object might look something 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.

Sample Request Body

{
  "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.

IMPORTANT: For Data Designer objects, if the user wants to ORDERBY Name, GSID, and any ther String datatypes fields, Gainsight recommends using tolower(<<fieldname>>). For Date, DateTime, and Number Datatypes users do not need to apply this.

 {
    "select": [
        "Id", --> it's NUMBER datatype
        "Name", --> It's a STRING datatype
        "tolower(Name)", ==> converting the Name field to lowercase
        "Plandate", --> It's a DATE datatype
        "PlanDateTime", --> It's a DATETIME datatype
        "Gsid", --> It's a STRING datatype
        "tolower(Gsid)", ==> converting the Gsid field to lowercase
        "GsCreatedDate", --> It's a DATETIME datatype
        "GsModifiedDate" --> It's a DATETIME datatype
    ],
    "orderBy": {
        "tolower(Name)": "asc",
        "tolower(Gsid)": "asc"
    },
    "limit": 5000,
    "offset": 1000
}

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, the 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. For more information on the supported formats, refer to the Gainsight Data Management article.

Parameters

Parameter (*mandatory)	Data type	Values	Description
select	String	-	A String value that contains a list of fields for which data needs to be retrieved.
conditions	List	-	A List value that contains all the conditions required for filtering the data.
name	String	-	A String value that contains the name of the field.
alias	String	-	A String value that contains the alias of the filter expression.
value	String	-	A String value that contains different values to compare names for conditions.
operator	String	-	A String value that contains the operator to be used for filtering data.
expression	String	-	A String value that contains the expression of the filter execution in case there are multiple conditions.
orderBy	String	-	A String value that contains the clause to specify the order in which the records should be returned - ascending or descending.
limit	Number	-	A Number value that contains the maximum number of records to be fetched with one Read API hit.
offset	Number	-	A Number value that contains the starting index of the records of the object.

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

Sample 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.

Sample Failure 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 to the Error Codes for Company and Custom Object APIs article.

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

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "b277a27b-316f-45e8-8bd1-37bbb2eb17ef",
    "data": {
        "records": []
    },
    "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

DELETE

Endpoint URL

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

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

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

The actual Delete Endpoint URL might look something like ...gainsightcloud.com/v1/data/objects/thisObject__gc/1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ

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

Sample 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": "6e2308e4-5e44-419b-af2a-21cd9153258c",
    "data": "Delete process initiated for 1 records.",
    "message": null
}

Sample Failure 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 to the Error Codes for Company and Custom Object APIs article.

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

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "15402521-8d94-47ec-8126-ee56c45b7db0",
    "data": "Delete process initiated for 1 records.",
    "message": null
}

Error Codes

For the list of error codes associated with the Gainsight Custom Object API, refer to the Error Codes for Company and Custom Object APIs article.