Skip to main content
Gainsight Inc.

Person API Documentation

Introduction

This document provides details of REST APIs that can be used for creating and updating a single record in the Person and Company Person, and Relationship Person objects in the Gainsight’s Matrix Data Architecture (MDA).

Gainsight Person is an object model that has unique records to represent people in the real world. There are three objects, Person, Company Person, and Relationship Person in this model. Using an API in this document, you can create or update a person record and associate this record with a company and a Relationship. For more information, refer Gainsight Person Object Model.

Prerequisites

  • To use APIs in this document, make sure that required sub-domain or custom domain is created, ex: https://personapi.gainsightcloud.com or https://personapi.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 APIs to load records into the Company Person and Relationship Person objects, ensure that associated records are already inserted into the Company and Relationship objects.

API Authentication

API access is controlled using a unique Access Key. Contact Gainsight Support to generate an access key for your organization. Once you get your access key, you will have to pass this as part of the request header “accesskey” for all of your API requests into Gainsight. The AccessKey does not expire.

Upsert of Single Person Record

You can ingest a single person record using an API into the Person object. This person record can have multiple associations with companies and relationships, details of which can be ingested into the Company Person and Relationship Person objects using this API. Following are three different APIs explained in this section:

  • Upsert Person API
  • Upsert Person API with Association IDs or Lookup Details
  • Upsert Person API with only Company and Relationship Lookup

Upsert Person API

This Upsert API is used to insert or upsert a record into the Person object which is not associated with any Company or Relationship. This API validates all fields in the Person object before inserting a record. If the validation is successful, the record is inserted into the object. If the validation fails for this record on any field then the API call fails with a validation error.

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” 
New or Update Record JSON Passed through the Request Body This is the JSON that represents a new record that you create in the Person object or update an existing record. A sample JSON is shown in the below section Request Body.
Key Passed through the Request Body Email is the only field that helps to identify a record in the Person object. Passing this field through API request body is mandatory. Using this field, remaining fields in the Person object are updated or a new record is created.

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents insert or update a record in the Person object model.

Request Body

A new person record that has no company or relationship associations can be inserted into the Person object. Pass a record that you want to insert into the Person object in the request body. Fields in the object and their associated values are passed as key value pairs as shown below. Pass the record that needs to be inserted as an array item.

Notes:

  • Passing an Email of a person is mandatory, it is used as unique constraint to resolve an existing record in the Person object.
  • If you pass a record, the Email of which matches with the existing record in the Person object, remaining fields in the existing record are updated with other details.
{
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com"
}

Success Response

Successful API request will return HTTP status code 200 as response. Format of the response is as shown below. Success response contains unique GSID of new record from the Person object.

{
    "result": true,
    "requestId": "c9b81beb-218d-406a-b72b-e6ab3771e129",
    "data": {
        "status": "SUCCESS",
        "personGsid": "1P04QNK6ENCURXXDZWKNCUGVYYCE5MHTRE7D"
    }
}

Upsert Person API with Association IDs or Lookup Details

This Upsert API is used to insert or update one record per API call into the Gainsight Person model and this record can have multiple associations with one or multiple Companies and Relationships that are stored in the Company Person and Relationship Person objects.

This API validates all fields in the Person object model before inserting or updating a record. If the validation is successful, the record is inserted or updated into these objects. If the validation fails for this record on any field then the API call fails with a validation error. To update an existing person record, Email is used as a unique constraint to identify a person record and update values in the remaining fields. 

If the corresponding records already exist in the Company Person and/or Relationship Person objects, other fields in these objects are updated with the provided details through API request body.

Company ID and Relationship ID (GSID) can be passed through API request body to insert into the Company Person and Relationship Person objects respectively. Alternatively, Company ID and Relationship ID (GSID) can be fetched from the Company and Relationship objects using lookup configuration details passed through the API request body.

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” 
New or Update Record JSON Passed through the Request Body This is the JSON that represents a new record that you create in the Person object and its association records in the Company Person and Relationship Person objects or update the existing records. A sample JSON is shown in the below section Request Body.
Key Passed through the Request Body Email is the only field that helps to identify a record in the Person object. Passing this field through API request body is mandatory. Using this field, remaining fields in the Person object are updated or a new record is created. Similarly, Person ID, Company ID, and Relationship ID fields are used as keys to update records in the Company Person and Relationship Person objects.

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents insert or update a record in the Person object model.

Request Body

Pass a record that you want to insert into the Person, Company Person, and Relationship Person objects in the request body. Fields in an object and their associated values are passed as key value pairs as shown below. Pass the record that needs to be inserted as an array item. While inserting a record into the Company Person and Relationship objects, it fetches GSID from Person object using Email as unique constraint and updates other fields in the Person object with the provided details.

If you pass an Email of a person record through the API which is not available in the Person object, a new record is created in the Person object.  If you pass a record, Email/Person ID and Company ID/Company lookup details of which matches with the existing records in the Person and Company Person objects, remaining fields in the existing record can be updated with other details. Similarly using Email/Person ID and Relationship ID/Relationship lookup details as unique constraints, existing records in the Person and Relationship Person can be updated.

Request Body - API with Association IDs

A person can be associated with multiple companies and Relationships. "companies" and "relationships" fields data represent the list of company and relationship association records respectively. Pass each Company ID and Relationship ID as array items in the "companies" and "relationships" fields respectively. "IsPrimaryCompany" field helps to identify a primary company out of all the company associations but passing this field is not mandatory.

Notes:

  • Passing an Email of a person is mandatory if you do not pass Person GSID in the API. This helps to resolve a record in the Person object using Email.
  • If you pass a record, the Email and Company ID or Relationship ID of which matches with the existing records in the Person objects, remaining fields in the existing record are updated with other details.
  • Passing the Company ID or Relationship ID (GSIDs from the Company and Relationship objects) is mandatory. If you do not have a Company ID or Relationship ID, you can use lookup criteria as mentioned in the section Upsert API with Lookup Details.

Following is the sample Request Body:

{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@abc.com",
    "companies": [
        {
            "Company_ID":"1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJCCCA",
            "IsPrimaryCompany": "false"
        },
        {
            "Company_ID":"2J33V5ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBBD",
            "IsPrimaryCompany": "true",
            "relationships": [
                {
                  "Role": "Admin",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJAAA2"

        }
        ]
     } 
   ]  
}
Request Body - API with Association Lookup Details

A person can be associated with multiple companies and relationships. "companies" and "relationships" fields data represent the list of company and relationship association records respectively. You can fetch Company ID using lookup details provided in the API. You can pass search criteria in the Company ID field which works with the lookup configuration provided in the "lookups" field and fetches Company ID (GSID) of a record from the Company object that matches with the lookup search criteria. Similarly, you can fetch Relationship ID from the Relationship object using lookup details details and lookup configuration provided in the API.

Following is the sample Upsert API with lookup details:

  • It has person details like First name, Last name, and an EmaiI to insert or update a record in the Person object.
  • In the "companies" field, Name can be provided in the Company ID field as search criteria for the Company ID.
  • In the "relationships" field, Name can be provided in the Relationship ID field as search criteria for the Relationship ID.
  • Lookup configuration is provided in the "lookups" field as to search for a Name provided in the Company ID field in the Company object and fetch GSID from the Company object into Company Person. Similarly, you can fetch Relationship ID to the Relationship Person object by searching with Name in the Relationship object. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.

Note: Name field is selected here for the lookup search criteria but you can use any other field for the same.

{
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@abc.com",
    "companies": [
      {
            "Company_ID": {"Name" : "Drivedata"},
            "IsPrimaryCompany": "false"
        },
        {
            "Company_ID": {"Name" : "abc, Inc."},
            "IsPrimaryCompany": "true",
            "Relationships": [
              {
                        "Role": "Admin",
                        "IsPrimaryCompany": "true",
                          "Relationship_ID" : {"Name": "Asia Pacific"}
                      }
                  ]
        }
     ],
    "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   }
               },
               "relationships":{
                   "Relationship_ID": {
                       "searchFields" : ["Name"]
                   }
               }
     }
}
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.

{ 
 "companies": [
        {
            "Company_ID": {"Name" : "Drivedata"},
            "IsPrimaryCompany": "false"
        },
        {
            "Company_ID":{"Name" : "abc, Inc."},
            "IsPrimaryCompany": "true",
            "Relationships": [
              {
                        "Role": "Admin",
                        "IsPrimaryCompany": "true",
                          "Relationship_ID" : {"Name": "Asia Pacific"}
                      }
                  ]
        }
     ],
    "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   }
               },
               "relationships":{
                   "Relationship_ID": {
                       "searchFields" : ["Name"]
                   }
               }
     }
}

In the above Lookups code snippet, Name (Company Name) given in the Company ID field works as key to search the company record using the search criteria "Name" = "abc, Inc." and "Drivedata" and gets the corresponding GSID of the company record and Populate into the Company ID field in the Company Person object. Similarly, Name given in the Relationship ID field is used to search in the Relationship object and fetch Relationship ID into the Relationship Person object.

Data Import Lookup_Person.png

The above image shows how import lookup helps to fetch Company ID from Company to Company Person object. The same approach is applied to fetch Relationship ID also.

Success Response

Successful API request will return HTTP status code 200 as response. Format of the response is as shown below. Success response contains unique GSID of a record from the Person object.

{
    "result": true,
    "requestId": "eaa1520f-0b27-4468-86b0-17b4e94f1786",
    "data": {
        "status": "SUCCESS",
        "personGsid": "1P04QNK6ENCURXXDZWKNCUGVYYCE5MHTRE7D"
    }
}

Upsert API with only Company and Relationship Lookup

This Upsert API is used to insert multiple records per API call into the Company Person and Relationship Person objects that are tied to a unique record in the Person object. You can insert a record into the Company Person object with just Person ID and Company ID as these two fields are mandatory for a record in the Company Person object. Similarly, you can insert a record into the Relationship Person object with just Person ID and Relationship ID. The corresponding GSIDs from the Person, Company, and Relationship objects are fetched into these fields through import lookup configuration provided in the API request body.

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” 
New or Update Record JSON Passed through the Request Body This is the JSON that represents a new record that you create in the Company Person and Relationship Person. A sample JSON is shown in the below section Request Body.

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents insert or update a record in the Person, Company Person, and Relationship Person objects.

Request Body

Pass records that you want to insert into the Company Person and Relationship Person objects with only Person ID, Company ID, and Relationship IDs.

A person can be associated with multiple companies. "companies" and "relationships" fields data represents the list of Company and Relationship association records respectively. You can fetch Company ID and Relationship ID using lookup details provided in the API. To fetch Company ID, Person ID, and Relationship ID:

  • Pass search criteria in the Company ID field that works with the lookup configuration provided in the "lookups" field and fetches Company ID (GSID) of a record from the Company object that matches with the lookup search criteria.
  • Pass “Email” as a search criteria in the Person ID field that works with the lookup configuration provided in the "lookups" field and fetches Person ID (GSID) of a record that matches with the provided Email.
  • Similarly, pass search criteria in the Relationship ID field that works with the lookup configuration provided in the "lookups" field and fetches Relationship ID (GSID) of a record from the Relationship object that matches with the lookup search criteria.

If you pass a record, Email and Company ID of which matches with the existing record in the Person and Company Person objects, remaining fields in the existing record are updated with other details. Similarly, Email and Relationship ID of the new record matches with the existing record in the Person and Relationship Person objects, remaining fields in the existing record are updated with other details.

Following is the sample Upsert API with lookup details:

  • In the "companies" field, Name and Email are provided in the Company ID and Person ID fields respectively as search criteria to fetch values into the Company ID and Person ID fields. Similarly, Name is provided in the Relationship ID field to fetch a value into the Relationship ID.
  • Lookup configuration is provided in the "lookups" field as to search for a Name provided in the Company ID, Relationship ID fields in the Company and Relationship objects and fetch Company ID and Relationship ID. Similarly, passed Email matches with the Email in the Person object and fetches Person ID into the Company Person and Relationship Person. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.

A sample API:

{
    "companies" : [ 
      {
        "Company_ID": {"Name" : "abc, Inc."},
        "Person_ID": {"Email": "jsmith@abc.com"},
        "IsPrimaryCompany": "true",
        "relationships": [
            {
                "Role": "Admin",
                "IsPrimaryCompany": "true",
                "Relationship_ID" : {"Name": "Gainsight Admin"}
            }
        ]
      }
    ],
    "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   },
                  "Person_ID": {
                      "searchFields" : ["Email"]
                   }
               },
               "relationships":{
                   "Relationship_ID": {
                       "searchFields" : ["Name"]
            }
        }
    }
}

Success Response

Successful API request will return HTTP status code 200 as response. Format of the response is as shown below. Success response contains unique GSID of a record from the Person object.

{
    "result": true,
    "requestId": "093e78ca-47a0-4512-bd0f-01ea58e944ef",
    "data": {
        "status": "SUCCESS",
        "personGsid": "1P04QNK6ENCURXXDZW5XK6PQMFFDEBD8EL3K"
    }
}

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. Full list of Gainsight error codes, error descriptions, their reasons, and HTTP status codes will be provided soon.

In the following error response body, error description shows the reason for failure of this API, with the given Company ID lookup search criteria, no matching record is found in the Company object.

{
    "result": false,
    "requestId": "27b8df50-beed-48c8-9b00-c5aebf9a1bcc",
    "data": {
        "status": "FAILURE",
        "errors": [
            {
                "field": "Company_ID",
                "invalidValue": [
                    {
                       "Email": "abc, Inc.",
                       "Company_ID": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED"
                    }
                ],
                "errorCode": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED",
                "errorMessage": "ResolveLookupService source lookup field not resolved"
            }
        ]
    }
}

Upsert of multiple Person Records

You can upsert multiple person records using an API into the Person object. Each person record can have multiple associations with companies and relationships, details of which can be inserted in the Company Person and Relationship Person objects using these APIs. Following are two different APIs explained in this section:

  • Upsert Person API
  • Upsert Person API with Association IDs or Lookup Details

Multiple person records are always upserted using APIs through Async method. This is called Asynchronous method as you will not receive the API response immediately with a result of new or updated personGsid. It takes a maximum of 30 minutes to complete inserting or updating the records.

You will receive statusId instead in the API response which you can use to call Async Record Request status API. This status API responds with an API response with the status of the corresponding API call. If the Status of API call is Completed, the response API shows the status of upsert of each record. For more details on the Status API Response, refer Status API Response Body.

Upsert Person API

This Upsert API is used to insert or update multiple records into the Person object that are not associated with any Company or Relationship. You can insert a maximum of 50 records per API call.

This API validates all fields in the Person object before inserting or updating the records. Records are inserted or updated when validation is successful. If the validation fails for any record on any field, then those records are not inserted or updated and the API call responds with a validation error.

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” 
New or Update Records JSON Passed through the Request Body This is the JSON that represents new records that you create in the Person object or update the existing records. A sample JSON is shown in the below section Request Body.
Key Passed through the Request Body Email is the only field that helps to identify a record in the Person object. Passing this field through API request body is mandatory. Using this field, remaining fields in the Person object are updated or new records are created.

Endpoint URL

    
https://personapi.gainsightcloud.com/v1.0/api/people/async

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people: represents insert or update records in the Person object.
  • async: represents a method to insert or update multiple person records through one API call.

Request Body

New person records that have no company or relationship associations can be inserted into the Person object. Pass the records that you want to insert or 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.  Pass each record 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.

Notes: 

  • Passing an Email of a person is mandatory, as it is used as a unique constraint to resolve an existing record in the Person object.
  • If you pass a record, the Email of which matches with an existing record in the Person object, remaining fields in the existing record are updated with other details.
  • It takes a maximum of 30 minutes to complete inserting or updating the records.
[
  {
  "Name": "John Smith",
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com"
},{
  "Name": "Steven Ferguson",
  "FirstName": "Steven",
  "LastName": "Ferguson",
  "Email": "sferguson@drivedata.com"
},{
  "Name": "Amanda Churchill",
  "FirstName": "Amanda",
  "LastName": "Churchill",
  "Email": "achurchill@simplify.com"
}
]

API Response

API request will return HTTP status code 200 as response with status Id in the “data”. Format of the response is as shown below. In the following response, value in the “data” key "a679fc3e-2ae6-48c1-95b6-ed82f9b8619e" is status Id. You can pass this status Id in the Endpoint URL of Upsert Status API to get the status of bulk data upsert of person records.

{
    "result": true,
    "requestId": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
    "data": {
        "statusId": "e3f66752-bd71-4826-b9e0-892f7c0a841e"
    }
}

Upsert Person API with Association IDs or Lookup Details

The Upsert API is used to insert or update multiple records per API call into the Person object. This record can have multiple associations with Companies and Relationships. The associated details like Company ID and Relationship ID or its Lookup details are stored in the respective objects. You can upsert a maximum of 50 Person records per API call.

This API validates all fields in the Person object model before inserting or updating the records. Records are inserted or updated when validation is successful. If the validation fails for any record on any field then those records are not inserted or updated and the API call responds with the corresponding validation error. To update an existing person record, Email is used as a unique constraint to identify a person record and update values in the remaining fields.

If the corresponding records already exist in the Company Person and/or Relationship Person objects, other fields in these objects are updated with the provided details through API request body.

Company ID and Relationship ID (GSID) can be passed through API request body to insert into the Company Person and Relationship Person objects respectively. Alternatively, Company ID and Relationship ID (GSID) can be fetched from the Company and Relationship objects using lookup configuration details passed through the API request body.

It takes a maximum of 30 minutes to complete inserting or updating the records depending on the number of Company and Relationship associations.

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” 
New or Update Records JSON Passed through the Request Body This is the JSON that represents new records that you create in the Person object and its association records in the Company Person and Relationship Person objects or update the existing records. A sample JSON is shown in the below section Request Body.
Key Passed through the Request Body Email is the only field that helps to identify a record in the Person object. Passing this field through API request body is mandatory. Using this field, remaining fields in the Person object are updated or a new record is created. Similarly, Person ID, Company ID, and Relationship ID fields are used as keys to update existing records in the Company Person and Relationship Person objects.

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people/async

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents insert or update records in the Person object model.
  • async: represents a method to insert or update multiple person records through one API call.

Request Body

Pass records that you want to insert into the Person, Company Person, and Relationship Person objects in the request body. Fields in an 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 pass a maximum of 50 person records per API call.

While upserting a record into the Person object, it fetches GSID from Person object using Email as unique constraint and updates other fields in the Person object with the provided details. If you pass an Email of a person record which is not available in the Person object, a new record is created in the Person object. If you pass a record, Email/Person ID and Company ID/Company lookup details of which matches with the existing record in the Person and Company Person, remaining fields in the existing record are updated with other details. Similarly using Email/Person ID and Relationship ID/Relationship lookup details as unique constraints, existing records in the Person and Relationship Person can be updated.

Request Body - API with Association IDs

A person can be associated with multiple companies and Relationships. "companies" and "relationships" fields data represent the list of company and relationship association records respectively. Pass each Company ID and Relationship ID as array items in the "companies" and "relationships" fields respectively. "IsPrimaryCompany" field helps to identify a primary company out of all the company associations, but passing this field is not mandatory.

Notes:

  • Passing an Email of a person is mandatory if you do not pass Person GSID in the API. This helps to resolve a record in the Person object using Email.
  • If you pass a record, the Email and Company ID or Relationship ID of which matches with the existing records in the Person object model, remaining fields in the existing record are updated with other details.
  • Passing the Company ID or Relationship ID (GSIDs from the Company and Relationship objects) is mandatory. If you do not have a Company ID or Relationship ID, you can use lookup criteria as mentioned in the section Upsert API with Lookup Details.

Following is the Sample Request Body:

[
  {
  "Name": "John Smith",
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com",
  "companies": [
    {
      "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Admin",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
                }
            ]
      }
    ]
 },
 {
  "Name": "Steven Ferguson",
  "FirstName": "Steven",
  "LastName": "Ferguson",
  "Email": "sferguson@drivedata.com",
  "companies": [
    {
      "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Executive Sponsor",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
                }
            ]
      }
    ]
 },
 {
  "Name": "Amanda Churchill",
  "FirstName": "Amanda",
  "LastName": "Churchill",
  "Email": "achurchill@simplify.com",
  "companies": [
    {
      "Company_ID": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Decision Maker",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID": "7581e498-c37e-4057-8fc9-c8d4d543bbbb"
                }
            ]
      }
    ]
  }
]
Request Body - API with Association Lookup Details

A person can be associated with multiple companies and relationships. "companies" and "relationships" fields data represent the list of company and relationship association records respectively. You can fetch Company ID using lookup details provided in the API. You can pass search criteria in the Company ID field which works with the lookup configuration provided in the "lookups" field and fetches Company ID (GSID) of a record from the Company object that matches with the lookup search criteria. Similarly, you can fetch Relationship ID from the Relationship object using lookup details and lookup configuration provided in the API.

Following is the sample Upsert API with lookup details:

  • It has person details like First name, Last name, and an EmaiI to insert or update records in the Person object.
  • In the "companies" field, Name can be provided in the Company ID field as search criteria for the Company ID.
  • In the "relationships" field, Name can be provided in the Relationship ID field as search criteria for the Relationship ID.
  • Lookup configuration is provided in the "lookups" field as to search for a Name provided in the Company ID field in the Company object and fetch GSID from the Company object into Company Person. Similarly, you can fetch Relationship ID to the Relationship Person object by searching with Name in the Relationship object. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.

Note: Name field is selected here for the lookup search criteria, but you can use any other field for the same.

[
  {
  "Name": "John Smith",
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com",
  "companies": [
    {
      "Company_ID": {"Name" : "abc, Inc."},
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Admin",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID" : {"Name": "Asia Pacific"}
                }
            ]
      }
    ],
    "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   }
               },
               "relationships":{
                    "Relationship_ID": {
                       "searchFields" : ["Name"]
                   }
               }
     }
 },
 {
  "Name": "Steven Ferguson",
  "FirstName": "Steven",
  "LastName": "Ferguson",
  "Email": "sferguson@drivedata.com",
  "companies": [
    {
      "Company_ID": {"Name" : "Drive Data"},
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Executive Sponsor",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID" : {"Name": "South Central"}
                }
            ]
      }
    ],
   "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   }
               },
               "relationships":{
                    "Relationship_ID": {
                       "searchFields" : ["Name"]
                   }
               }
     }
 },
 {
  "Name": "Amanda Churchill",
  "FirstName": "Amanda",
  "LastName": "Churchill",
  "Email": "achurchill@simplify.com",
  "companies": [
    {
      "Company_ID":{"Name" : "Simplify, Inc."},
      "IsPrimaryCompany": "true",
      "relationships": [
        {
                  "Role": "Decision Maker",
                  "IsPrimaryCompany": "true",
                  "Relationship_ID" : {"Name": "Middle East"}
                }
            ]
      }
    ],
   "lookups" : {
               "companies":{
                   "Company_ID": {
                       "searchFields" : ["Name"]
                   }
               },
               "relationships":{
                    "Relationship_ID": {
                       "searchFields" : ["Name"]
                   }
               }
     }
 }
]

API Response

API request will return HTTP status code 200 as response with status Id in the “data”. Format of the response is as shown below. In the following response, value in the “data” key "a679fc3e-2ae6-48c1-95b6-ed82f9b8619e" is status Id. You can pass this status Id in the Endpoint URL of Upsert Status API to get the status of bulk data upsert of person records.

{
    "result": true,
    "requestId": "7581e498-c37e-4057-8fc9-c8d4d543de1a",
    "data": {
        "statusId": "e3f66752-bd71-4826-b9e0-892f7c0a841e"
    }
}

Upsert Status API

This API is used to obtain the processing status of the person record request that has been passed through any of the Async Upsert APIs. You need Status Id, generated as a response to any Async upsert API call to get processing status. Pass this Status Id as part of Endpoint URL and you will receive the status in the API Response Body.

Method Details

HTTP Method GET
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” 
Status Id Passed through the Endpoint URL Status Id represents the job id that is generated when an Async Upsert API record request is submitted.

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people/async/status/{statusId}

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • async: represents a method to insert or update multiple person records through one API call.
  • statusId: represents the job id that is generated when an Async Upsert API record request is submitted through an API.

With statusId, Endpoint URL looks like /v1.0/api/people/async/status/a679fc3e-2ae6-48c1-95b6-ed82f9b8619e

Response Body

This status API responds with an API response having status of the corresponding API call. You may receive one of the following status:

  • INIT (Initiated)
  • INPROGRESS
  • COMPLETED

Following is the sample API response with status INIT:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "status": "INIT"
    }
}

Following is the sample API response with status INPROGRESS:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "status": "INPROGRESS"
    }
}

It may take a maximum of 30 minutes to complete inserting or updating the records. Status is displayed as either INIT or INPROGRESS until the upsert is completed. If the status of API call is COMPLETED, the API response body has the following information:

  • Upsert status of each record with either SUCCESS or FAILURE.
  • personGsid of each record successfully inserted or updated.
  • Error details of the failed upsert of a record like errorCode, errorMessage, and other error details.

Full list of Gainsight error codes, error descriptions, and their reasons will be provided soon.

Following is the sample API response with status COMPLETED and SUCCESS in upserting all the records:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "response": [
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVSLYPA6V8DCGNQ58SZ8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVUISQCMJQ7AR3H72NS8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVH1M411WI4YP6E2JJSY"
            }
        ],
        "status": "COMPLETED"
    }
}

Following is the sample API response with status COMPLETED and SUCCESS in upserting some records and FAILURE in upserting some records with error details:

{
    "result": true,
    "requestId": "069360c6-03b3-4acf-8c7e-17ae0963ecd2",
    "data": {
        "response": [
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVSLYPA6V8DCGNQ58SZ8"
            },
            {
                "status": "SUCCESS",
                "personGsid": "1P04FB5W1VECWNJCCVUISQCMJQ7AR3H72NS8"
            },
            {
                "status": "FAILURE",
                "errors": [
                  {
                "field": "Company_ID",
                "invalidValue": [
                    {
                        "Name": "Simplify, Inc.",
                        "Company_ID":  "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED"
                    }
                ],
                "errorCode": "RLS_SOURCE_LOOKUP_FIELD_NOT_RESOLVED",
                "errorMessage": "ResolveLookupService source lookup field not resolved"
            }
]
            }
        ],
        "status": "COMPLETED"
    }
}

Get a Person Record

Get Person API with GSID

Get API allows you to get one record per API call from the Person, Company Person, and Relationship Person objects associated with a Person GSID passed in the Endpoint URL.

Method Details

HTTP Method GET
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” 

Endpoint URL

https://personapi.gainsightcloud.com/v1.0/api/people/gsid

In this endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents fetching a record from the Person, Company Person, and Relationship Person objects.
  • gsid: It represents a unique GSID of a person record. This helps to fetch details of a record from the Person object and it’s company and relationship association details from the Company Person and Relationship Person objects respectively.

Success Response

Successful API request will return HTTP status code 200 as response. Format of the success response is as shown below. If GSID passed in the endpoint URL matches with the person gsid of an existing record, system fetches values of each field in the Person, Company Person, and Relationship Person objects. If there is no value existing in a field, it results null in the success response. A sample success response is shown below:

{
    "result": true,
    "requestId": "b31b204c-6df8-444a-bfc7-d922a98bbebe",
    "data": {
        "email": "jsmith@abc.com",
        "createddate": "2018-06-05T12:03:16.417",
        "firstname": "John",
        "timezone": null,
        "dynamicresolutionkey": null,
        "modifieddate": "2018-06-05T12:03:16.417",
        "name": "John Smith",
        "lastname": "smith",
        "externalrecordid__gc": null,
        "masterrecordid": null,
        "middlename": null,
        "masteravatartypecode": null,
        "location": "United States",
        "gsid": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
        "companies": [
            {
                "modifieddate": "2018-06-05T12:04:10.81",
                "company_id": {
                    "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                    "name": "abc, Inc."
                },
                "gsid": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1",
                "active": true,
                "isprimarycompany": null,
                "role": "1I0054U9FAKXZ0H26H4PSEVL0V2MP7H680C4",
                "manager": null,
                "createddate": "2018-06-05T12:04:10.81",
                "person_id": {
                    "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                    "name": "John Smith"
                },
                "title": "Executive Sponsor",
                "relationships": [
                    {
                        "person_id": {
                            "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                            "name": "John Smith"
                        },
                        "relationship_type_id": null,
                        "manager": null,
                        "company_id": {
                            "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                            "name": "abc, Inc."
                        },
                        "createddate": "2018-06-05T12:06:29.023",
                        "isprimarycompany": null,
                        "role": null,
                        "relationship_id": {
                            "Id": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBB1",
                            "name": "Asia Pacific"
                        },
                        "gsid": "1C03IGJ69L7HWHM6EZQ1WP8952BL2V8GKCY8",
                        "title": "Executive Sponsor",
                        "company_person_id": {
                            "Id": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1"
                        },
                        "active": true,
                        "modifieddate": "2018-06-05T12:06:29.023"
                    }
                ]
            }
        ]
    }
}

In the above sample success response:

  • data field has field:value pairs from the Person object
  • companies field has field:value pairs from the Company Person object that also includes lookup fields company id and person id and the respective values from the Name fields.
  • relationships field has field:value pairs from the Relationship Person object that also includes lookup fields company id, relationship id, person id, and the respective values from the Name fields.

Get Person API with Email

Get API allows you to get one record per API call from the Person, Company Person, and Relationship Person objects associated with a Person GSID passed in the Endpoint URL.

Method Details

HTTP Method GET
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” 

Endpoint URL

/v1.0/api/people?Email=jsmith@abc.com

In the above Endpoint URL:

  • https://personapi.gainsightcloud.com is the domain through which you can connect to Gainsight. It is just for reference only.
  • people represents fetching a record from the Person, Company Person, and Relationship Person objects.
  • gsid: It represents a unique GSID of a person record. This helps to fetch details of a record from the Person object and it’s company and relationship association details from the Company Person and Relationship Person objects respectively.

Success Response

Successful API request will return HTTP status code 200 as response. Format of the success response is as shown below. Email mentioned in the endpoint URL is used as a unique identifier to identify a record in the Person object and fetches values from each field of this record in the Person, Company Person, and Relationship Person objects. If there is no value existing in a field, it results null in the success response. A sample success response is shown below:

{
    "result": true,
    "requestId": "b31b204c-6df8-444a-bfc7-d922a98bbebe",
    "data": {
        "email": "jsmith@abc.com",
        "createddate": "2018-06-05T12:03:16.417",
        "firstname": "John",
        "timezone": null,
        "dynamicresolutionkey": null,
        "modifieddate": "2018-06-05T12:03:16.417",
        "name": "John Smith",
        "lastname": "smith",
        "externalrecordid__gc": null,
        "masterrecordid": null,
        "middlename": null,
        "masteravatartypecode": null,
        "location": "United States",
        "gsid": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
        "companies": [
            {
                "modifieddate": "2018-06-05T12:04:10.81",
                "company_id": {
                    "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                    "name": "abc, Inc."
                },
                "gsid": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1",
                "active": true,
                "isprimarycompany": null,
                "role": "1I0054U9FAKXZ0H26H4PSEVL0V2MP7H680C4",
                "manager": null,
                "createddate": "2018-06-05T12:04:10.81",
                "person_id": {
                    "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                    "name": "John Smith"
                },
                "title": "Executive Sponsor",
                "relationships": [
                    {
                        "person_id": {
                            "Id": "1P04AB23JMJA97MWFYJM8PQO1KQTAYV5MXJ1",
                            "name": "John Smith"
                        },
                        "relationship_type_id": null,
                        "manager": null,
                        "company_id": {
                            "Id": "1P04QNK6ENCURXXDZW9WWWWWWWWWWTZCAAAA",
                            "name": "abc, Inc."
                        },
                        "createddate": "2018-06-05T12:06:29.023",
                        "isprimarycompany": null,
                        "role": null,
                        "relationship_id": {
                            "Id": "1I00V4ALRX6A6ZOEQ0FNJ3CXSRAVFFWJBBB1",
                            "name": "Asia Pacific"
                        },
                        "gsid": "1C03IGJ69L7HWHM6EZQ1WP8952BL2V8GKCY8",
                        "title": "Executive Sponsor",
                        "company_person_id": {
                            "Id": "1C01KDEEJ1EH9CQP5LE79JLEPK9AH63AKWS1"
                        },
                        "active": true,
                        "modifieddate": "2018-06-05T12:06:29.023"
                    }
                ]
            }
        ]
    }
}

In the above sample success response:

  • data field has field:value pairs from the Person object
  • companies field has field:value pairs from the Company Person object that also includes lookup fields company id, person id, and the respective values from the Name fields.
  • relationships field has field:value pairs from the Relationship Person object that also includes lookup fields company id, relationship id, person id, and the respective values from the Name fields.
  • Was this article helpful?