Skip to main content
Gainsight Inc.

Gainsight Bulk REST APIs

  1. Last updated
  2. Save as PDF

This article explains the REST APIs that can be used to fetch bulk data from Gainsight Custom objects, Standard objects, and System objects, and check job status.

IMPORTANT: Gainsight bulk APIs limit is 10 calls per hour/100 per day

Prerequisites

To use APIs in this document, make sure that the required sub-domain or custom domain is created.

For example: https://customobjectapi.gainsightcloud.com or https://customobjectapi.yourcompany.com

Note: You can add your domain in the Endpoint URL to connect to Gainsight.

For more information on how to create a domain, refer to the Setup a Gainsight Domain article.

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

Download Gainsight Custom Object Data

To download the data from Gainsight custom object, follow the three steps:

  1. Submit Bulk Job Request
  2. Bulk API Job Status
  3. Fetch Chunk Data

Submit Bulk Job Request

This API can be used to submit the bulk job request to download the data from Gainsight custom object.

Method Details

API Details Description
Request Method POST
Request Endpoint

https://<customer domain>/v3/exports/data/bulk/{objectName}

Note: Replace <customer domain> and {objectName} with your company domain and the object name to submit the job request.
Header
  • content-type: application/json
  • accept: application/json, text/plain, */*
  • accept-language: en-GB,en-US;q=0.9,en;q=0.8
  • authentication: <Access Key>

Sample Request

{
  "select": [
    "Name",
    "Csm",
    "Csm__gr.name",
    "Billing_State__gc",
    "Industry",
    "Segment__gc",
    "Unique_ID__gc"
  ],
  "where": {
    "conditions": [
      {
        "name": "Name",
        "alias": "A",
        "value": [
          "Gainsight"
        ],
        "operator": "CONTAINS"
      },
      {
        "name": "Csm__gr.name",
        "alias": "B",
        "value": [
          "J"
        ],
        "operator": "CONTAINS"
      }
    ],
    "expression": "A OR B"
  },
  "orderBy": {
    "Name": "asc",
    "Csm__gr.name": "desc"
  },
  "limit": 100000,
  "offset": 0
}

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, For example: EQ: Equals, CONTAINS, GREATER THAN, etc. Refer to the Supported Operators section 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
    • If no limit is passed by default the limit will be set to 1 million. example: “Limit”:1000000
  • 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.
    • if no offset is passed the by default offset will be set to 0.
Supported Operators

 

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_NUL Is not null
CONTAINS Contains
DOES_NOT_CONTAINS Does not contains
STARTS_WITH Starts with
ENDS_WITH Ends with
INCLUDES /IN Includes
EXCLUDES/ NOT_IN Excludes

Sample Success Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "e0fb8d9d-76e6-4bdf-bd17-476429a4b214",
    "data": {
        "jobId": "f19962b9-fb47-4f8d-84e3-218ab6146cab",
        "statusURL": "v3/exports/data/job/status/f19962b9-fb47-4f8d-84e3-218ab6146cab",
      }
    "message": null
}

Sample Failure Response

  • If no select field is passed.
{
    "result": false,
    "errorCode": "GSOBJ_ESS_9104",
    "errorDesc": "Atleast one select field should be included in the payload.",
    "requestId": "c16b2fc9-09e7-4bec-b2bb-b611ff2972c3",
    "data": null,
    "message": null
}
  • Invalid select fields or invalid limits etc.
{
    "result": false,
    "errorCode": "GSOBJ_ESS_9150",
    "errorDesc": "Malformed Query Exception.",
    "requestId": "a3e168fa-4fcc-4475-9938-83a1c553b0b8",
    "data": null,
    "message": null
}

Bulk API Job Status

This API can be used to check the job status of the Bulk API. The job response will contain the status of the job, it will be either in progress, completed, or failed.

Method Details

API Details Description
Request Method GET
Request Endpoint

https://<customer domain>/{statusURL}

Note: Replace <customer domain> and {statusURL} with your company domain and the actual status URL to check the job status. The statusURL is returned in the job submitted response for the job.
Header
  • content-type: application/json
  • accept: application/json, text/plain, */*
  • accept-language: en-GB,en-US;q=0.9,en;q=0.8
  • authentication: <Access Key>

Sample In-Progress Response

If the job is still progressing the response will contain jobStatus as IN_PROGRESS.

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "62988764-9e59-4a68-bfdc-069b9bbe783c",
    "data": {
        "jobId": "15f435bf-fb69-4901-a265-ba6e206f38f8",
        "jobStatus": "IN_PROGRESS"
    },
    "message": null
}

Sample Success Response

If the job is completed then the response’s data will contain jobStatus as COMPLETED.

Response will contain the chunkDetails, Based on the size of the exported data the number of chunks will be generated. Each chunk will have a corresponding chunkURL which is needed to fetch that particular chunk data. Along with the chunkURL corresponding limit and offset for that chunk will be returned.

Total exported records will be present in totalRecords of the response’s data.

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "9486dd24-ec9d-4ef9-b6af-862a978b2155",
  "data": {
    "jobId": "c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a",
    "jobStatus": "COMPLETED",
    "totalRecords": 28954,
    "chunkDetails": [
      {
        "chunkURL": "v3/exports/data/job/c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a/chunk/1/results",
        "offset": 0,
        "limit": 20000
      },
      {
        "chunkURL": "v3/exports/data/job/c49e1eef-2c54-41c2-94a0-6b4b0cd92a8a/chunk/2/results",
        "offset": 20000,
        "limit": 8954
      }
    ]
  },
  "message": null
}

Sample Failure Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "95e0a38b-181e-475a-bbff-1e6ae269a568",
    "data": {
        "jobId": "15f435bf-fb69-4901-a265-ba6e206f38f8",
        "jobStatus": "FAILED",
        "errorDesc": "Malformed Query Exception.",
        "errorCode": "GSOBJ_ESS_9150",
        "internalRequestId": "85f84db8-0672-4005-a160-7796c9bb9188"
    },
    "message": null
}

Fetch Chunk Data

This API can be used to download large amounts of data in chunks (multiple files). You can download the data by using the chunk URL found in the job status response.

Method Details

API Details Description
Request Method GET
Request Endpoint

https://<customer domain>/{chunkURL}

Note: Replace <customer domain> and {chunkURL} with your company domain and actual chunk URL to fetch the chunk data. The chunkURL is returned in job status for the completed jobs.
Header
  • content-type: application/json
  • accept: application/json, text/plain, */*
  • accept-language: en-GB,en-US;q=0.9,en;q=0.8
  • authentication: <Access Key>

Sample Response

"Name","Csm","Csm__gr.name","Billing_State__gc","Industry","Segment__gc","Unique_ID__gc"
"Acme","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Latisha Jones","Kansas","Government","Mid-Market","JB000056"
"Foo","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Latisha Jones","Virginia","Technology","Mid-Market","JB000021"
"Gainsight","1P01E316G9DAPFOLE6RE341037M38PORO8VE","Mathew","Texas","Non-profit","Mid-Market","JB000111"
  1. Back to top
  • Was this article helpful?

Recommended articles

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