Company API Documentation
Gainsight NXT
This article explains details of REST APIs that can be used for creating, updating, reading, and deleting records in the Gainsight Company object.
Introduction
It 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. This is an external API.
Prerequisites
-
To use APIs in this document, make sure that required sub-domain or custom domain is created, ex: https://companyapi.gainsightcloud.com or https://companyapi.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 Company object APIs, ensure that:
- Company object is installed in your tenant.
- 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:
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.
Note: The AccessKey does not expire.
Headers
Key |
Value |
---|---|
Accesskey |
For more information on Access key, Gainsight admin can refer to Generate API Access Key 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 (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.
Insert API
The 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
POST
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.
Sample Request Body
{ "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 the same or another object. Ensure that you pass the fields of GSID type to populate GSID from the 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 one 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 one to lookup to the same object and fetch GSID of 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 respond 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).
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).
Parameters
Parameters* |
Data Type | Values (if any) | Description |
---|---|---|---|
Name* | String |
- |
A String value that contains the Company Name. |
Industry | String | - | A String value that contains an Industry Name. |
ARR | Currency | - | A Currency value that contains the Annual Recurring Revenue. |
Employees | Number | - | A Number value that contains the count of employees the company has. |
LifeCycleInWeeks | Number | - | A Number value that contains the number of weeks the entire process goes through. |
OriginalContractDate | Date | - | A Date value that contains the date the engagement with the client started. |
RenewalDate | Date | - | A Date value that contains he upcoming renewal date of the contract. |
Stage | Dropdownlist | New Customer Kicked Off Launched Adopting Will Churn Churn |
A Dropdownlist value that contains the current stage of the Company in the sales pipeline. |
Status |
Dropdownlist |
Active Inactive Churn |
A Dropdownlist value that contains current status. |
CSMFirstName | String | - | A String value that contains the first name of the POC of the company. |
CSMLastName | String | - | A String value that contains the last name of the POC of the company. |
ParentCompanyName | String | - | A String value that contains the Parent Company Name. |
Sample Success Response
{ "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 }
Sample Failure Response
{ "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
PUT
Endpoint URL
https://companyapi.gainsightcloud.com/v1/data/objects/Company?keys=fieldName1,fieldName2
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 object name.
- Keys are Employees and Industry, a valid endpoint URL to update record(s) in the Company object looks like https://companyapi.gainsightcloud.com/v1/data/objects/Company?keys=Employees,Industry.
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.
Sample Request Body
{ "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" } } }
Parameters
Parameters* |
Data Type | Values (if any) | Description |
---|---|---|---|
Industry | String | - | A String value that contains an Industry Name. |
ARR | Currency | - | A Currency value that contains the Annual Recurring Revenue. |
Employees | Number | - | A Number value that contains the count of employees the company has. |
LifeCycleInWeeks | Number | - | A Number value that contains the number of weeks the entire process goes through. |
OriginalContractDate | Date | - | A Date value that contains the date at which the engagement with the client started. |
RenewalDate | Date | - | A Date value that contains the upcoming renewal date of the contract. |
Stage |
Dropdownlist |
New Customer Kicked Off Launched Adopting Will Churn Churn |
A Dropdownlist value that contains the current stage of the Company in the sales pipeline. |
Status | Dropdownlist |
Active |
A Dropdownlist value that contains the current status. |
CSMFirstName | String | - | A String value that contains the first name of the POC of the company. |
CSMLastName | String | - |
A String value that contains the last name of the POC of the company. |
Sample Success Response
{ "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 }
Sample Failure Response
{ "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 to the Read API Sample Request Body section.
Method
POST
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.
Sample Request Body
{ "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 }
Parameters
Parameters* |
Data Type | Values (if any) | Description |
---|---|---|---|
Name | String | - | A String value that contains a Company Name. |
Renewal_Date | Currency | - | A Currency value that contains the upcoming renewal date of the contract. |
Stage | Dropdownlist | - | A Dropdownlist value that contains the current stage of the Company in the sales pipeline. |
Customer_lifetime_in_Months | Number | - | A Number value that contains the number of months a typical customer is associated with the company. |
csm_ _gr.email | - | A Email value that contains the CSM's email ID. |
Sample Success Response
{ "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 }
Sample Failure Response
{ "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
DELETE
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.
Sample Success Response
{ "result": true, "errorCode": null, "errorDesc": null, "requestId": "8863e73c-a465-4fc6-a385-f7b3200720dc", "data": "Record with GSID: 1I0054U9FAKXZ0H26H4H0U5VRD65H9JW66FJ successfully deleted.", "message": null }
Sample Failure Response
{ "result": false, "errorCode": "GSOBJ_1XXX", "errorDesc": "No data found for given criteria", "requestId": "58222b97-eaf0-402e-854d-1914987c4b49", "data": null, "message": null }
Error Codes
For information about the error codes for the Relationship APIs, refer to the Error Codes for Company, Relationship, and Custom Object APIs article.