Skip to main content
Gainsight Inc.

Company API Documentation

  1. Last updated
  2. Save as PDF

Introduction

This document provides details of REST APIs that can be used for creating, updating, reading, and deleting records in the Company object. Company is the Gainsight’s standard object in Matrix Data Architecture (MDA) that stores your individual customer records and their company information. 

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

  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:

Company Object Fields.png

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’s Company 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://companyapi.gainsightcloud.com/v1/data/objects/Company

In this endpoint URL:

  • https://companyapi.gainsightcloud.com is the domain through which you connect to Gainsight. It is just for reference only.
  • Company is the Gainsight standard object into which you want to insert records.

Request Body

Pass the records that you want to insert into the Company 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 Company object:

{
  "records": [
    {
      "Name": "Acme",
      "Industry": "Software",
      "ARR": 250000,
      "Employees": 840,
      "LifecycleInWeeks": 15,
      "OriginalContractDate": "12-14-2017",
      "RenewalDate": "12-13-2018",
      "Stage": "Adopting",
      "Status": "Active",
      "CSMFirstName": "Steve",
      "CSMLastName": "Smith",
      "ParentCompanyName": "KLM Software"
    },
    {
      "Name": "Heroku",
      "Industry": "Networking",
      "ARR": 200000,
      "Employees": 480,
      "LifecycleInWeeks": 7,
      "OriginalContractDate": "04-30-2018",
      "RenewalDate": "04-29-2019",
      "Stage": "Kicked Off",
      "Status": "Active",
      "CSMFirstName": "Joe",
      "CSMLastName": "Roberts",
      "ParentCompanyName": "Telenet"
    },
    {
      "Name": "DriveData",
      "Industry": "Hardware",
      "ARR": 260000,
      "Employees": 560,
      "LifecycleInWeeks": 18,
      "OriginalContractDate": "05-31-2018",
      "RenewalDate": "05-30-2019",
      "Stage": "New Customer",
      "Status": "Active",
      "CSMFirstName": "Mark",
      "CSMLastName": "Lehmann",
      "ParentCompanyName": "Superbiz Inc."
    },
    {
      "Name": "ABC Corp.",
      "Industry": "Healthcare",
      "ARR": 340000,
      "Employees": 950,
      "LifecycleInWeeks": 28,
      "OriginalContractDate": "01-15-2018",
      "RenewalDate": "01-14-2019",
      "Stage": "Launched",
      "Status": "Active",
      "CSMFirstName": "Michelle",
      "CSMLastName": "Williams",
      "ParentCompanyName": "Power Health Group"
    },
    {
      "Name": "XYZ Inc.",
      "Industry": "Marketing",
      "ARR": 450000,
      "Employees": 280,
      "LifecycleInWeeks": 23,
      "OriginalContractDate": "05-30-2018",
      "RenewalDate": "05-29-2018",
      "Stage": "Adopting",
      "Status": "Active",
      "CSMFirstName": "Josh",
      "CSMLastName": "Wood",
      "ParentCompanyName": "Marketive"
    }
  ],
  "lookups": {
    "CSM": {
      "fields": {
        "CSMFirstName": "FirstName",
        "CSMLastName": "LastName"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "ParentCompany": {
      "fields": {
        "ParentCompanyName": "Name"
      },
      "lookupField": "Gsid",
      "objectName": "company",
      "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 same or another object. Ensure that you pass the fields of GSID type to populate GSID from same or another object. One JSON applies for Lookups to all the records that are inserted to populate fields of GSID data type.

There are two types of lookups: Direct and Self. Direct lookup enables to lookup to another standard object and fetch GSIDs of the records from the lookup object. Lookup configuration for the CSM field shown in the snippet below is an example of the Direct lookup.

Self lookup enables to lookup to the same object and fetch GSID of the another record to the target field. Lookup configuration for the Parent Company field shown in the snippet below is an example of the Self lookup.

{
  "lookups": {
    "CSM": {
      "fields": {
        "CSMFirstName": "FirstName",
        "CSMLastName": "LastName"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "ParentCompany": {
      "fields": {
        "ParentCompanyName": "Name"
      },
      "lookupField": "Gsid",
      "objectName": "company",
      "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.
  • “ParentCompanyName” (in request body): “Name” (field name in the Company object to match)
  • “lookupField”: “Gsid” (lookup field name), Ex: GS User > GSID or Company > GSID
  • “objectName” : “gsuser” (lookup object name), Ex: GS User (Direct Lookup) or Company (Self Lookup).

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 Lookup object.
  • MARKASERROR: This option lets the system responds with an error when multiple records match the criteria between JSON and the Lookup 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 Lookup object.
Direct Import Lookup

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

Direct Import Lookup.png

Self Import Lookup

For example, in the below code snippet, Parent Company field is populated with GSID from the same object, Company by matching ParentCompanyName (in request body) with Name (in Company object).

Self Import Lookup.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 and Parent Company fields for each record are successfully 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 are populated with a unique GSID of an item.
{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
  "data": {
    "records": [
      {
        "CreatedDate": 1521691459693,
        "Name": "Acme",
        "Industry": "Software",
        "ARR": 250000,
        "Employees": 840,
        "LifecycleInWeeks": 15,
        "OriginalContractDate": 1531691459792,
        "RenewalDate": 1543691459853,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1562691459623,
        "Gsid": "1P02MRXML1GRDV44YOYPEBMABN5JYVTAATP8",
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "Parentcompany": "1P02MRXML1GRDV44YOL2I8HX2NJNQTEE"
      },
      {
        "CreatedDate": 1521691459693,
        "Name": "Heroku",
        "Industry": "Networking",
        "ARR": 200000,
        "Employees": 480,
        "LifecycleInWeeks": 7,
        "OriginalContractDate": 1531691459792,
        "RenewalDate": 1543691459853,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO6NO2DQXRNTQYQXDLGF",
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "Parentcompany": "8P02MRXML1GRDV44YO6QXRNTQYQXDLGF"
      },
      {
        "CreatedDate": 1521691459693,
        "Name": "DriveData",
        "Industry": "Hardware",
        "ARR": 260000,
        "Employees": 560,
        "LifecycleInWeeks": 18,
        "OriginalContractDate": 1531691459792,
        "RenewalDate": 1543691459853,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YOL2PI8HX2NJRH5NQTEE",
        "Csm": "1P01OI3OHC9S79J7VN1DW2NKI9JJFXEVHIZK",
        "Parentcompany": "2P02MRXML1GRDV44YO2PVGD1NMPG69BD"
      },
      {
        "CreatedDate": 1521691459693,
        "Name": "ABC Corp.",
        "Industry": "Healthcare",
        "ARR": 340000,
        "Employees": 950,
        "LifecycleInWeeks": 28,
        "OriginalContractDate": 1531691459792,
        "RenewalDate": 1543691459853,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Parentcompany": "1P01OI3OHC9S79J7VN8QDH0Y52CYFMXW"
      },
      {
        "CreatedDate": 1521691459693,
        "Name": "XYZ Inc.",
        "Industry": "Marketing",
        "ARR": 450000,
        "Employees": 280,
        "LifecycleInWeeks": 23,
        "OriginalContractDate": 1531691459792,
        "RenewalDate": 1543691459853,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "ModifiedDate": 1241672475612,
        "Gsid": "1P02MRXML1GRDV44YO87PCQFV0QIRSDZZ3DN",
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Parentcompany": "4P01OI3OHC9S79J7VN8QUF0Y52CYFMXW"
      }
    ]
  },
  "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 “OriginalContractDate”.

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

Update API

Update API is used to update one or more existing records in the Company 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://companyapi.gainsightcloud.com/v1/data/objects/Company?keys=fieldName1,fieldName2

In this Endpoint URL:

Note: Keys (field names) used above are just for reference only. You can pass any field from the Company object as Key in the Endpoint URL that meets following conditions.

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 “Employees” and “Industry” 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": [
    {
      "Industry": "Marketing",
      "ARR": 520000,
      "Employees": 280,
      "LifecycleInWeeks": 23,
      "OriginalContractDate": "12-20-2017",
      "RenewalDate": "12-19-2018",
      "Stage": "Launched",
      "Status": "Active",
      "CSMFirstName": "Mark",
      "CSMLastName": "Taylor"
    },
    {
      "Industry": "Healthcare",
      "ARR": 390000,
      "Employees": 950,
      "LifecycleInWeeks": 28,
      "OriginalContractDate": "10-15-2017",
      "RenewalDate": "10-14-2018",
      "Stage": "Will Churn",
      "Status": "Inactive",
      "CSMFirstName": "Julia",
      "CSMLastName": "Brown"
    }
  ],
  "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 the 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": [
      {
        "CreatedDate": 1521691459694,
        "Name": "XYZ Inc.",
        "Industry": "Marketing",
        "ARR": 520000,
        "Employees": 280,
        "LifecycleInWeeks": 23,
        "OriginalContractDate": 1521743018667,
        "RenewalDate": 1521691459694,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "ModifiedDate": 1521743018667,
        "Gsid": "1P02MRXML1GRDV44YO87PCQFV0QIRSDZZ3DN",
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Parentcompany": "4P01OI3OHC9S79J7VN8QUF0Y52CYFMXW"
      },
      {
        "CreatedDate": 1521691459694,
        "Name": "ABC Corp.",
        "Industry": "Healthcare",
        "ARR": 390000,
        "Employees": 950,
        "LifecycleInWeeks": 28,
        "OriginalContractDate": 1521743018667,
        "RenewalDate": 1521691459694,
        "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
        "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "ModifiedDate": 1521743018667,
        "Gsid": "1P02MRXML1GRDV44YO2PVJIALGD1NMPG69CA",
        "Csm": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
        "Parentcompany": "1P01OI3OHC9S79J7VN8QDH0Y52CYFMXW"
      }
    ]
  },
  "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 = 210318).",
  "requestId": "7cba3c98-b04b-4e21-9e57-44807fa52b8a",
  "data": {
    "count": 0,
    "errors": [
      [
        {
          "success": false,
          "parsedValue": 210318,
          "errors": [
            {
              "errorMessage": "Invalid dateTime format",
              "errorCode": "GSOBJ_1006",
              "fieldName": "OriginalContractDate",
              "invalidValue": 210318
            }
          ]
        }
      ]
    ],
    "records": null
  },
  "message": null
}

Read API

Read API allows you to read one or more records that match a specific criteria from the Company object. 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 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://companyapi.gainsightcloud.com/v1/data/objects/query/Company

In this endpoint URL:

  • https://companyapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • Company is the Gainsight standard object from which you want to read the records.

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

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": [
    "Name",
    "Renewal_Date",
    "Status",
    "Stage",
    "Customer_Lifetime_in_Months",
    "csm__gr.email"
  ],
  "where": {
    "conditions": [
      {
        "name": "Renewal_Date",
        "alias": "A",
        "value": [
          "03-22-2018",
          "05-21-2018"
        ],
        "operator": "BTW"
      },
      {
        "name": "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 records that match criteria.
  • Field: Stage / Values: New Customer, Kicked off, Launched / Operator: IN. In this condition, 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.

Fields mentioned in the “Select” section of the API request body will be returned for all the records matching the query criteria mentioned in the “Where” conditions. In the above request body, “select” fields mentioned are:

  • Name
  • Renewal Date
  • Status
  • Customer Lifetime in Months
  • csm_gr.email: You can use lookup fields in the Read API to fetch values from another object (not Company object). In the above sample API, a lookup field csm__gr.email is used. This field has lookup from the Company Object > User object (via csm field in Company) > email (field in the User object). From the given field, email is fetched from the User object using lookups. You can use multiple lookups to different objects to fetch values from another object.

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. A sample Success Response is shown below:

  • 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": "8863e73c-a465-4fc6-a385-f7b3200720dc",
  "data": [
    {
      "Name": "Heroku",
      "Renewal_Date": 1521743018667,
      "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
      "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
      "Customer_Lifetime_in_Months": 22,
      "csm__gr.email": "jnash@heroku.com"
    },
    {
      "Name": "ABC Inc.",
      "Renewal_Date": 1521743018667,
      "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
      "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
      "Customer_Lifetime_in_Months": 15,
      "csm__gr.email": "cbrown@abc.com"
    },
    {
      "Name": "XYZ Inc.",
      "Renewal_Date": 1521743018667,
      "Status": "1P01OI3OHC9S79J7VN8GQLUQDH0Y52CYFMXW",
      "Stage": "1I0054U9FAKXZ0H26HO92M3F1G5SPWVQDNF3",
      "Customer_Lifetime_in_Months": 6,
      "csm__gr.email": "dbess@xyz.com"
    }
  ],
  "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 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 the Company 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://companyapi.gainsightcloud.com/v1/data/objects/Company/GSID

In this endpoint URL:

  • https://companyapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • Company is the Gainsight standard object from which you want to delete a record.
  • GSID is the unique ID of an existing record in the Company object, for example, 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ.

Actual Delete Endpoint URL may look like https://companyapi.gainsightcloud.co...5VRD65H9JW66FJ.

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
}
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Custom Filter
    Admin Guides
    Draft Workflow
    Ready to Publish
  2. Tags
    This page has no tags.