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 or multiple records 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.
  • Pass field names as Keys that are as captured from the Data Management schema as shown below:

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

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 represents the list of company and relationship association records respectively. You can fetch Company ID using import lookup configuration provided in the API request body. You can pass Company Name 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 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, Pass key value pairs that helps you to match with fields from the Company object and fetch GSID from the Company object and populate into target field Company ID.
  • In the "relationships" field, Pass key value pairs that helps you to match with fields from the Relationship object and fetch GSID from the Relationship object and populate into target field Relationship ID.
  • Lookup configuration is provided in the "lookups" field as to match fields passed in the “companies” with fields passed in the lookup configuration and populate GSID from Company object to Company ID field in the Company Person object. Similarly, you can fetch Relationship ID to the Relationship Person object using import lookup configuration. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.
  • You can also populate values into any custom field of GSID data type using import lookup configuration.
  • Passing lookup details like lookupField, objectName, multiMatchOption, onNoMatch is not mandatory to populate GSID into standard fields like Person ID, Company ID, Relationship ID, etc. It is required to pass them for custom fields of GSID data type.
  • If you do not pass lookup details, system considers default options for "multiMatchOption": "FIRSTMATCH" and "onNoMatch": "ERROR".
{
  "FirstName": "John",
  "LastName": "Smith",
  "Email": "jsmith@abc.com",
  "companies": [
    {
      "CompanyName": "Drivedata",
      "IsPrimaryCompany": "false",
      "role": "Power User",
      "CustomObject__column1": 9234567891
    },
    {
      "CompanyName": "abc, Inc.",
      "IsPrimaryCompany": "true",
      "Relationships": [
        {
          "role": "Admin",
          "IsPrimaryCompany": "true",
          "RelationshipName": "Asia Pacific"
        }
      ]
    }
  ],
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Company",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      },
      "Deskphone__gc": {
        "fields": {
          "CustomObject__column1": "Phone_num_custom_column"
        },
        "lookupField": "Gsid",
        "objectName": "custom_table_name",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Relationship",
        "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 another object in Gainsight. Ensure that you pass the fields of GSID type to populate GSID from another object. One JSON applies for Lookups to all the records that are inserted to populate field of GSID data type.

{
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Company",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      },
      "Deskphone__gc": {
        "fields": {
          "CustomObject__column1": "Phone_num_custom_column"
        },
        "lookupField": "Gsid",
        "objectName": "custom_table_name",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        },
        "lookupField": "Gsid",
        "objectName": "Relationship",
        "multiMatchOption": "FIRSTMATCH",
        "onNoMatch": "ERROR"
      }
    }
  }
}

In the above Lookups code snippet, keys are defined as below:

  • “CompanyName” (in request body): “Name” (field name in the Company object to match)

Note: You can pass multiple fields from the source to match with the multiple lookup fields (Ex: to find the right match).

  • “CustomObject__column1” (in request body): “Phone_num_custom_column” (field name in the “custom_table_name” object to match)
  • “lookupField”: “Gsid” (lookup field name), Ex: Company > GSID and custom_table_name > CustomObject__column1
  • “objectName” : (lookup object name), Ex: Company or custom_table_name.

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.

Person Import Lookup_V1.png

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

Request Body - API with only Relationship Association

A person can be associated with multiple companies and relationships. You can insert or update one or multiple person records with only Relationship association details (without their respective company association details). You can pass the relationship association details in the Request body along with person details either by Relationship ID or relationship lookup details. "relationships" fields data represents the list of relationship association records. You can fetch Relationship ID using import lookup configuration provided in the API request body. You can pass Relationship Name field which 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. While fetching Relationship ID using lookup, the associated Company ID is also fetched from the Company object.

Following is the sample Upsert API with lookup details:

{
  "FirstName": "John",
  "LastName": "Smith",
  "Name": "John Smith",
  "Email": "jsmith@abc.com",
  "relationships": [
    {
      "Role": "Admin",
      "IsPrimaryCompany": "true",
      "RelationshipName": "Asia Pacific"
    }
  ],
  "lookups": {
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "Name"
        }
      }
    }
  }
}

In the above sample API, to learn more on the person and lookup details, refer Request Body - API with Association Lookup Details.

Notes:

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 import lookup configuration provided in the API request body. To fetch Company ID, Person ID, and Relationship ID:

  • Pass “Email” as key value pair that helps you to match with Email field from the Person object using "lookup details" and identify a record in the Person object to tie the person details that are passed in the API.
  • In the "companies" field, Pass key value pairs that helps you to match with fields from the Company object using "lookup details" and fetches GSID from the Company object and populate into target field Company 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.
  • Similarly, you can fetch Relationship ID to the Relationship Person object using import lookup configuration. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.
  • You can also populate values into any custom field of GSID data type using import lookup configuration.
  • Passing lookup details like lookupField, objectName, multiMatchOption, onNoMatch is not mandatory to populate GSID into standard fields like Person ID, Company ID, Relationship ID, etc. It is required to pass them for custom fields of GSID data type.
  • If you do not pass lookup details, system considers default options for "multiMatchOption": "FIRSTMATCH" and "onNoMatch": "ERROR".

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, "CompanyName" and "PersonEmail" work with lookups configuration to fetch values into the Company ID and Person ID fields. Similarly, "RelationshipName" is provided to fetch a value into the Relationship ID using lookup details.
  • Lookup configuration is provided in the "lookups" field as to search for a Name provided in the Company Name, Relationship Name 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 existing Person ID into the Company Person and Relationship Person objects. 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": [
    {
      "CompanyName": "abc, Inc.",
      "PersonEmail": "jsmith@abc.com",
      "IsPrimaryCompany": "true",
      "relationships": [
        {
          "Role": "Admin",
          "IsPrimaryCompany": "true",
          "RelationshipName": "Asia Pacific"
        }
      ]
    }
  ],
  "lookups": {
    "companies": {
      "Company_ID": {
        "fields": {
          "CompanyName": "Name"
        }
      },
      "Person_ID": {
        "fields": {
          "PersonEmail": "Email"
        }
      }
    },
    "relationships": {
      "Relationship_ID": {
        "fields": {
          "RelationshipName": "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, refer Error Codes for Person API.

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 Company Name 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 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, Pass key value pairs that helps you to match with fields from the Company object and fetch GSID from the Company object and populate into target field Company ID.
  • In the "relationships" field, Pass key value pairs that helps you to match with fields from the Relationship object and fetch GSID from the Relationship object and populate into target field Relationship ID.
  • Lookup configuration is provided in the "lookups" field as to match fields passed in the “companies” with fields passed in the lookup configuration and populate GSID from Company object to Company ID field in the Company Person object. Similarly, you can fetch Relationship ID to the Relationship Person object using import lookup configuration. For more information on the import lookup configuration to load values in the GSID type fields, refer the section Import Lookup.
  • You can also populate values into any custom field of GSID data type using import lookup configuration.
  • Passing lookup details like lookupField, objectName, multiMatchOption, onNoMatch is not mandatory to populate GSID into standard fields like Person ID, Company ID, Relationship ID, etc. It is required to pass them for custom fields of GSID data type.
  • If you do not pass lookup details, system considers default options for "multiMatchOption": "FIRSTMATCH" and "onNoMatch": "ERROR".
[
  {
    "Name": "John Smith",
    "FirstName": "John",
    "LastName": "Smith",
    "Email": "jsmith@abc.com",
    "companies": [
      {
        "CompanyName": "abc, Inc.",
        "IsPrimaryCompany": "true",
        "relationships": [
          {
            "Role": "Admin",
            "IsPrimaryCompany": "true",
            "RelationshipName": "Asia Pacific"
          }
        ]
      }
    ],
    "lookups": {
      "companies": {
        "Company_ID": {
          "fields": {
            "CompanyName": "Name"
          }
        }
      },
      "relationships": {
        "Relationship_ID": {
          "fields": {
            "RelationshipName": "Name"
          }
        }
      }
    }
  },
  {
    "Name": "Steven Ferguson",
    "FirstName": "Steven",
    "LastName": "Ferguson",
    "Email": "sferguson@drivedata.com",
    "companies": [
      {
        "CompanyName": "Drive Data",
        "IsPrimaryCompany": "true",
        "relationships": [
          {
            "Role": "Executive Sponsor",
            "IsPrimaryCompany": "true",
            "RelationshipName": "South Central"
          }
        ]
      }
    ],
    "lookups": {
      "companies": {
        "Company_ID": {
          "fields": {
            "CompanyName": "Name"
          }
        }
      },
      "relationships": {
        "Relationship_ID": {
          "fields": {
            "RelationshipName": "Name"
          }
        }
      }
    }
  },
  {
    "Name": "Amanda Churchill",
    "FirstName": "Amanda",
    "LastName": "Churchill",
    "Email": "achurchill@simplify.com",
    "companies": [
      {
        "CompanyName": "Simplify, Inc.",
        "IsPrimaryCompany": "true",
        "relationships": [
          {
            "Role": "Decision Maker",
            "IsPrimaryCompany": "true",
            "RelationshipName": "Middle East"
          }
        ]
      }
    ],
    "lookups": {
      "companies": {
        "Company_ID": {
          "fields": {
            "CompanyName": "Name"
          }
        }
      },
      "relationships": {
        "Relationship_ID": {
          "fields": {
            "RelationshipName": "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, refer Error Codes for Person API.

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

https://personapi.gainsightcloud.com/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?