Skip to main content
Gainsight Inc.

People API Documentation

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

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, you can create or update a person record and associate this record with a company and a Relationship. For more information, refer to the Gainsight Person Object Model article.

In this document, mainly two sets of APIs are explained:

  • People API
  • People APIs - Bulk

The People APIs - Bulk differs from the People API in terms of the number of records that can be ingested  per call. For more information, refer to the People APIs - Bulk section.

IMPORTANT: From now on, the Person API is renamed as the People API.

Gainsight API Limits

The following are the recommended API limits for Gainsight APIs (The exact limits can vary based on your package):

  • Synchronous API Calls: 100 API calls per min / 50,000 API call per day
  • Asynchronous API Calls (Gainsight bulk APIs limit): 10 calls per hour / 100 per day

Note: All of the above API limits are *Fixed window rate limits.

* Fixed window rate limiting restricts the number of API requests at a specific time. For example, a server can have a rate limiting component that implements a fixed window algorithm that only accepts 100 requests per minute. The time-frame is fixed, and it starts at a specific time. For example, the server will only serve 100 requests between 10:00 am, and 10:01 am.

Prerequisites

  • 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. Please reach out to your Gainsight Admin to confirm availability of these records in the Gainsight's 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 to the Generate API Access Key article.

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.

People API

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

/ Authorization

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/peoplemgmt/v1.0/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 a 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

/ Authorization

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/peoplemgmt/v1.0/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 a 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 the import lookup configuration provided in the API request body. You can pass the 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 to 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 respond 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

/ Authorization

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/peoplemgmt/v1.0/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 a key value pair that helps you to match with the 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 to 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, the 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 to 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

/ Authorization

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/peoplemgmt/v1.0/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.
{
  "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

/ Authorization

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/peoplemgmt/v1.0/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:

{
  "records": [
    {
      "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" field 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 the 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 the target field Company ID.
  • In the "relationships" field, Pass key value pairs that help you to match with fields from the Relationship object and fetch GSID from the Relationship object and populate into the target field Relationship ID.
  • Lookup configuration is provided in the "lookups" field 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".
{
  "records": [
    {
      "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

/ Authorization

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/peoplemgmt/v1.0/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/peoplemgmt/v1.0/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

/ Authorization

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/peoplemgmt/v1.0/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

/ Authorization

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/peoplemgmt/v1.0/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.

Delete Person Records

Delete API

Person Delete API can be used to delete Person record(s) from Gainsight. When the person record(s) are deleted, their corresponding records from the Company Person, Relationship Person, and person references in other Gainsight objects are deleted.

This API helps with adherence to General Data Protection Regulation (GDPR) by deleting unwanted person records from Gainsight. GDPR states that companies should not store their customer’s unwanted personal data. Compliance requires companies to clear all Personally identifiable information (PII) customer data from all systems that the companies use (including Gainsight). 

Person Delete API is used to delete person records from the Gainsight Person object. Every record in the Person object is identified with a unique GSID. You should pass the GSIDs that you want to delete, through the request body of this API.

Note: Dependent fields in other Gainsight custom objects having lookup to Person GSID are honoured with On Delete setting in the dependent field configuration.

Method Details

/ Authorization

HTTP Method DELETE
Content Type application/json
Response Format JSON
Requires Authentication Yes
Header Accesskey

 

Required Parameters How To Use Description
API Key Passed through the Request Header Pass the API Access key you received from Gainsight in the header “Accesskey” 

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/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 identifying record(s) to delete from the Person, Company Person, and Relationship Person objects.

You can pass GSIDs of the person records through the Request Body of this API. The respective person records, their corresponding records from the Company Person, Relationship Person, and person references in other Gainsight objects are deleted.

[
"1P04ARSY3839P6I6ECT3SZV21QW0RHARBU90",
"1P04ARSY3839P6I6ECN85PJ739P2QLZE2QKW",
"1P04ARSY3839P6I6ECKAX77N1RIABCUJ59GK"
]

Notes:

  • You can pass a maximum of 5000 GSIDs per API call to delete them from the Gainsight Person object. 

  • You can make a maximum of 100 Delete API calls per hour.

Sample response for the Delete API returns with deleteRequestId, status, and count. deleteRequestId represents the status id of the job submitted and helps you get the status of deleting person records using GET Delete status API. status represents the status of the job. You can see one of the following three status:

  • INIT - initialisation, request accepted

  • INPROGRESS - request in progress

  • COMPLETED - request completed

count represents the number of records processed in a job.

{
    "result": true,
    "requestId": "b69ffec9-0893-400e-93ce-47824a888c52",
    "data": {
        "deleteRequestId": "b69ffec9-0893-400e-93ce-47824a888c52",
        "status": "INIT",
        "count": 0
    }
}

GET Delete Status API

This API helps you get the current status of the delete request submitted through Delete API. Once a delete request is submitted, it takes some time to delete the respective person records. You can check this latest delete status through GET Delete Status API.

Method Details

/ Authorization

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/peoplemgmt/v1.0/people/delete/status/{deleteRequestId}

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 identifying record(s) from the Person, Company Person, and Relationship Person objects to check the delete status.

  • deleteRequestId helps you get the status of the request for deleting person records. For more information on the deleteRequestId, refer to the Delete API section.

Sample Response

Sample response for the GET Delete Status API returns with deleteRequestId, status, and count. deleteRequestId is the Id that you have passed in the Endpoint URL. status represents the status of the Delete API job. You can see one of the following three status:

  • INIT - initialisation, request accepted

  • INPROGRESS - request in progress

  • COMPLETED - request completed

count represents the number of records processed in the Delete API job.

{
    "result": true,
    "requestId": "1b49a9e7-935a-47b2-b5ff-5f9c5dcd14b7",
    "data": {
        "deleteRequestId": "b69ffec9-0893-400e-93ce-47824a888c52",
        "status": "COMPLETED",
        "count": 1
    }
}

People APIs - Bulk

The People APIs - Bulk, helps ingest multiple people records in an API call. This API has significant improvements in terms of the number of records it can accept per call.

The following table showcases the difference between People API and People APIs -Bulk in terms of ingesting the number of records per call as follows:

API Types


People API Limits

People APIs -Bulk Limits


Sync

1 record per call


50 records per call
Async 50 records per call 80 MB per call

The People APIs - Bulk provides a comprehensive solution for managing person records, associating them with multiple companies, and establishing relationships within Gainsight. People APIs- Bulk, which is an external API, consists of various details such as name, first name, and email. Additional parameters can be included as key-value pairs in the request, if required. The email field serves as a unique constraint and is used to identify the person's record.

People Upsert Record Request

This API is required to load data into Person, CompanyPerson, and RelationshipPerson associations.

Note: In each request, the number of records and fields can contain a maximum of 50 records only.

Method

PUT

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/external/bulk/ingestion/people

Sample Request Body

{
    "records": [
        {
            "Name": "John Smith",
            "FirstName": "John",
            "LastName": "Smith",
            "Email": "jsmith@gs.com",
            "companies": [
                {
                    "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Admin",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                        },
                        {
                            "Role": "Admin",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                        }
                    ]
                }
            ]
        },
        {
            "Name": "Steven Ferguson",
            "FirstName": "Steven",
            "LastName": "Ferguson",
            "Email": "sferguson@drivedata.com",
            "companies": [
                {
                    "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Executive Sponsor",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
                        }
                    ]
                }, {
                    "Company_ID": "1P022A6Z2DWEK48YJME2XUU84B6OTTHEXDH6",
                    "IsPrimaryCompany": "true",
                    "relationships": [
                        {
                            "Role": "Executive Sponsor",
                            "IsPrimaryCompany": "true",
                            "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
                        }
                    ]
                }
            ]
        }
    ]
}

Parameters

Parameter (*mandatory)

Data Type

Value (if any)

Description

Email *

String


-

This is used as a unique constraint to identify the person's record.


Companies

JSON Object
 

-
This represents the list of Company association records.

Company_ID *

String

-
A GSID value that stores the GSID of the Company.

Person_ID *


String
-

A Gsid value that stores the Gsid of the Company.

IsPrimaryCompany

Boolean


-
A GSID value that stores the GSID of the Person.

relationships

JSON Object

-
This represents the list of Relationships associations in the context of the company record.

Relationship_ID *


String

-

A GSID value that stores the GSID of the Relationship.

 

Relationship_Type_ID *


String

-
A GSID value that stores the GSID of the Relationship Type.

Sample Success Response

{
    "result": true,
    "requestId": "afef3724-2986-4b38-a3df-6f85fe9ecc9a",
    "data": {
        "successCount": 2,
        "totalCount": 2,
        "failureCount": 0,
        "partialSuccessCount": 0,
        "records": [
            {
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Admin",
                                    "Active": "true",
                                    "Gsid": "1C03LJDGQOSVO8PI22W60V6L2FMFPIHL0Z4T",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                                    "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2KAHJ8ZERPSOLRPTZ8N",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": "1P05X6HJ5J89CAI334N38ATFRMA8D6GUSQ0R"
                                }
                            ],
                            "Gsid": "1C01V3KWK4FX057IQ2KAHJ8ZERPSOLRPTZ8N",
                            "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                            "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "johnsmith@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                    "FirstName": "John",
                    "LastName": "Smith",
                    "Name": "John Smith",
                    "Location": "California, US"
                },
                "messageId": "1",
                "rowNumber": 1,
                "operationStatus": "SUCCESS"
            },
            {
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Executive Sponsor",
                                    "Active": "true",
                                    "Gsid": "1C03LJDGQOSVO8PI22T0JUF6EJEHZAFAB2TD",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                                    "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2EUU0N7IPI7GKQEXY32",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": "1P05X6HJ5J89CAI334N38ATFRMA8D6GUSQ0R"
                                }
                            ],
                            "Gsid": "1C01V3KWK4FX057IQ2EUU0N7IPI7GKQEXY32",
                            "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "stevenferguson@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                    "FirstName": "Steven",
                    "LastName": "Ferguson",
                    "Name": "Steven Ferguson",
                    "Location": "California, US"
                },
                "messageId": "2",
                "rowNumber": 2,
                "operationStatus": "SUCCESS"
            }
        ]
    }
}

Sample Partial Response

{
    "result": true,
    "requestId": "9edf5547-6d33-428f-9c01-3e6441e55889",
    "data": {
        "successCount": 0,
        "totalCount": 2,
        "failureCount": 0,
        "partialSuccessCount": 2,
        "records": [
            {
                "error": {
                    "rowNum": 1,
                    "details": [
                        {
                            "fieldName": "Company_ID,Person_ID,Relationship_ID",
                            "values": {
                                "Company_ID,Person_ID,Relationship_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Company_ID,Person_ID,Relationship_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Admin",
                                    "Gsid": "1C03LJDGQOSVO8PI225VAOGS7UFCW3K7U2EN",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                                },
                                {
                                    "Role": "Admin",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true"
                                }
                            ],
                            "Gsid": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "johnsmith@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                    "FirstName": "John",
                    "LastName": "Smith",
                    "Name": "John Smith",
                    "Location": "California, US"
                },
                "messageId": "1",
                "rowNumber": 1,
                "operationStatus": "PARTIAL_SUCCESS"
            },
            {
                "error": {
                    "rowNum": 2,
                    "details": [
                        {
                            "fieldName": "Company_ID,Person_ID,Relationship_ID",
                            "values": {
                                "Company_ID,Person_ID,Relationship_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Company_ID,Person_ID,Relationship_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [],
                            "Gsid": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                            "IsPrimaryCompany": "true"
                        },
                        {
                            "relationships": [
                                {
                                    "Role": "Executive Sponsor",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true"
                                }
                            ],
                            "Gsid": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "stevenferguson@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                    "FirstName": "Steven",
                    "LastName": "Ferguson",
                    "Name": "Steven Ferguson",
                    "Location": "California, US"
                },
                "messageId": "2",
                "rowNumber": 2,
                "operationStatus": "PARTIAL_SUCCESS"
            }
        ]
    }
}

Sample Failure Response

{
    "result": true,
    "requestId": "16a72fb5-da2f-4597-84f7-cfb6a72bcb75",
    "data": {
        "successCount": 0,
        "totalCount": 2,
        "failureCount": 2,
        "partialSuccessCount": 0,
        "records": [
            {
                "error": {
                    "rowNum": 1,
                    "details": [
                        {
                            "fieldName": "Email",
                            "values": {
                                "Email": "johnsmith@"
                            },
                            "errors": [
                                {
                                    "message": "Invalid email value",
                                    "code": "GSOBJ_VDTEMAIL1001"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID",
                            "values": {
                                "Company_ID,Person_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID,Relationship_ID",
                            "values": {
                                "Company_ID,Person_ID,Relationship_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID,Relationship_ID",
                            "values": {
                                "Company_ID,Person_ID,Relationship_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Admin",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                                },
                                {
                                    "Role": "Admin",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "IsPrimaryCompany": "true"
                                }
                            ],
                            "Active": "true",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "johnsmith@",
                    "EmailOptOut": "false",
                    "FirstName": "John",
                    "LastName": "Smith",
                    "Name": "John Smith",
                    "Location": "California, US"
                },
                "messageId": "1",
                "rowNumber": 1,
                "operationStatus": "FAILURE"
            },
            {
                "error": {
                    "rowNum": 2,
                    "details": [
                        {
                            "fieldName": "Email",
                            "values": {
                                "Email": "stevenferguson@"
                            },
                            "errors": [
                                {
                                    "message": "Invalid email value",
                                    "code": "GSOBJ_VDTEMAIL1001"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID",
                            "values": {
                                "Company_ID,Person_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        },
                        {
                            "errors": [
                                {
                                    "message": "Row with the given resolution key already exists : {Company_ID=1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O, Person_ID=null}",
                                    "code": "GSOBJ_VCUSTOM1007"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID",
                            "values": {
                                "Company_ID,Person_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID,Person_ID,Relationship_ID",
                            "values": {
                                "Company_ID,Person_ID,Relationship_ID": {
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Resolution key value is null or empty : Person_ID",
                                    "code": "GSOBJ_VCUSTOM1012"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [],
                            "Active": "true",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "IsPrimaryCompany": "true"
                        },
                        {
                            "relationships": [
                                {
                                    "Role": "Executive Sponsor",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                                    "IsPrimaryCompany": "true"
                                }
                            ],
                            "Active": "true",
                            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "stevenferguson@",
                    "EmailOptOut": "false",
                    "FirstName": "Steven",
                    "LastName": "Ferguson",
                    "Name": "Steven Ferguson",
                    "Location": "California, US"
                },
                "messageId": "2",
                "rowNumber": 2,
                "operationStatus": "FAILURE"
            }
        ]
    }
}

People - Upsert Record Request with Lookup Details

This API upserts the person, companies, and relationships associations after resolving the given lookup details.

Note: In each request, the number of records and fields can contain a maximum of 50 objects only.

Method

PUT

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/external/bulk/ingestion/people'

Sample Request Body

'{
    "lookups": {
        "relationships": {
            "Relationship_ID": {
                "objectName": "relationship",
                "onNoMatch": "ERROR",
                "multiMatchOption": "FIRSTMATCH",
                "fields": {
                    "RelationshipName": "Name"
                },
                "lookupField": "Gsid"
            }
        },
        "companies": {
            "Company_ID": {
                "objectName": "company",
                "onNoMatch": "ERROR",
                "multiMatchOption": "FIRSTMATCH",
                "fields": {
                    "CompanyName": "Name"
                },
                "lookupField": "Gsid"
            }
        }
    },
    "records": [
        {
            "companies": [
                {
                    "relationships": [
                        {
                            "RelationshipName": "Relationship1",
                            "IsPrimaryCompany": "True"
                        }
                    ],
                    "CompanyName": "Broadcom",
                    "IsPrimaryCompany": "True"
                }
            ],
            "Email": "janedoe@gmail.com",
            "FirstName": "Jane",
            "LastName": "Doe",
            "Name": "Jane Doe"
        }
    ]}'

Parameters

Parameter (*mandatory)

Data Type

Value (if any)

Description


lookupField 

String


-
This specifies the target field where the data should be populated after resolving it from the lookup.

objectName 

String

-
This indicates the object name from which the lookup needs to be referenced.
multiMatchOption 
String

-
It is considered if multiple matches occur for the lookup.

onNoMatch 

String
- It  is considered if none of the existing records match the input parameter.

Sample Success Response

{
    "result": true,
    "requestId": "96aff241-c491-46bb-b06f-6c5b89593ee8",
    "data": {
        "successCount": 1,
        "totalCount": 1,
        "failureCount": 0,
        "partialSuccessCount": 0,
        "records": [
            {
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Active": "true",
                                    "Gsid": "1C030AY77URN4L94V7QHYXOVHLIIVPKRW0KG",
                                    "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                                    "Person_ID": "1P04BR1UNP9RWC9Y6WFR2D66U5MI3G1TW6PM",
                                    "Company_Person_ID": "1C01AXKEWJ9B3044W92TBFGSS2W4IVQK9OSX",
                                    "IsPrimaryCompany": "True",
                                    "CurrencyIsoCode": "USD",
                                    "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
                                }
                            ],
                            "Active": "true",
                            "Gsid": "1C01AXKEWJ9B3044W92TBFGSS2W4IVQK9OSX",
                            "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                            "Person_ID": "1P04BR1UNP9RWC9Y6WFR2D66U5MI3G1TW6PM",
                            "IsPrimaryCompany": "True",
                            "CurrencyIsoCode": "USD"
                        }
                    ],
                    "Email": "janedoe@gmail.com",
                    "EmailOptOut": "false",
                    "Gsid": "1P04BR1UNP9RWC9Y6WFR2D66U5MI3G1TW6PM",
                    "FirstName": "Jane",
                    "LastName": "Doe",
                    "CurrencyIsoCode": "USD",
                    "Name": "Jane Doe"
                },
                "messageId": "1",
                "rowNumber": 1,
                "operationStatus": "SUCCESS"
            }
        ]
    }
}

Sample Failure Response

{
    "result": true,
    "requestId": "be21edae-74d7-472b-b09b-e64307d83195",
    "data": {
        "successCount": 0,
        "totalCount": 2,
        "failureCount": 0,
        "partialSuccessCount": 2,
        "records": [
            {
                "error": {
                    "rowNum": 1,
                    "details": [
                        {
                            "fieldName": "Company_ID",
                            "values": {
                                "Company_ID": {
                                    "lookupData": {
                                        "Company_ID": "GSOBJ_RLS012"
                                    },
                                    "errorCode": "GSOBJ_RLS012"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Invalid gsid value",
                                    "code": "GSOBJ_VDTGSID1001"
                                }
                            ]
                        },
                        {
                            "fieldName": "Company_ID",
                            "values": {
                                "Company_ID": {
                                    "lookupData": {
                                        "Company_ID": "GSOBJ_RLS012"
                                    },
                                    "errorCode": "GSOBJ_RLS012"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Invalid gsid value",
                                    "code": "GSOBJ_VDTGSID1001"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Admin",
                                    "Active": "true",
                                    "Company_ID": {
                                        "lookupData": {
                                            "Company_ID": "GSOBJ_RLS012"
                                        },
                                        "errorCode": "GSOBJ_RLS012"
                                    },
                                    "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": "1P05X6HJ5J89CAI334N38ATFRMA8D6GUSQ0R"
                                }
                            ],
                            "Active": "true",
                            "cp_checkbox_default__gc": "true",
                            "Company_ID": {
                                "lookupData": {
                                    "Company_ID": "GSOBJ_RLS012"
                                },
                                "errorCode": "GSOBJ_RLS012"
                            },
                            "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "johnsmith@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                    "FirstName": "John",
                    "LastName": "Smith",
                    "Name": "John Smith",
                    "Location": "California, US"
                },
                "messageId": "1",
                "rowNumber": 1,
                "operationStatus": "PARTIAL_SUCCESS"
            },
            {
                "error": {
                    "rowNum": 2,
                    "details": [
                        {
                            "fieldName": "Relationship_ID",
                            "values": {
                                "Relationship_ID": {
                                    "lookupData": {
                                        "Relationship_ID": "GSOBJ_RLS012"
                                    },
                                    "errorCode": "GSOBJ_RLS012"
                                }
                            },
                            "errors": [
                                {
                                    "message": "Invalid gsid value",
                                    "code": "GSOBJ_VDTGSID1001"
                                }
                            ]
                        }
                    ]
                },
                "record": {
                    "companies": [
                        {
                            "relationships": [
                                {
                                    "Role": "Executive Sponsor",
                                    "Active": "true",
                                    "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                                    "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                                    "Company_Person_ID": "1C01V3KWK4FX057IQ2EUU0N7IPI7GKQEXY32",
                                    "rp_checkbox_default__gc": "true",
                                    "IsPrimaryCompany": "true",
                                    "Relationship_ID": {
                                        "lookupData": {
                                            "Relationship_ID": "GSOBJ_RLS012"
                                        },
                                        "errorCode": "GSOBJ_RLS012"
                                    }
                                }
                            ],
                            "Gsid": "1C01V3KWK4FX057IQ2EUU0N7IPI7GKQEXY32",
                            "Company_ID": "1P0287ONRQ5E7UYP6VV2GBXDD7Z9HAX28ZWP",
                            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                            "IsPrimaryCompany": "true"
                        }
                    ],
                    "Email": "stevenferguson@gs.com",
                    "Gsid": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                    "FirstName": "Steven",
                    "LastName": "Ferguson",
                    "Name": "Steven Ferguson",
                    "Location": "California, US"
                },
                "messageId": "2",
                "rowNumber": 2,
                "operationStatus": "PARTIAL_SUCCESS"
            }
        ]
    }
}

People APIs - Bulk Async Process

This API is required to load data into People Module using a JSON File.

Note: The maximum file size allowed in each request is 80 MB.

Method

POST

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/external/bulk/ingestion/async/people

Sample Request Body

{
"records"
:
[
{
"FirstName"
:
"FirstName0"
,
"LastName"
:
"LastName0"
,
"Email"
:
"testemail0@gs.com"
,
"Name"
:
"Name0"
}
,
{
"FirstName"
:
"FirstName1"
,
"LastName"
:
"LastName1"
,
"Email"
:
"testemail1@gs.com"
,
"Name"
:
"Name1"
}
,
{
"FirstName"
:
"FirstName2"
,
"LastName"
:
"LastName2"
,
"Email"
:
"testemail2@gs.com"
,
"Name"
:
"Name2"
}
,
{
"FirstName"
:
"FirstName3"
,
"LastName"
:
"LastName3"
,
"Email"
:
"testemail3@gs.com"
,
"Name"
:
"Name3"
}
]
}

Parameters

Parameter (*mandatory)

Data Type

Value (if any)

Description


jobId

String


-
This represents the status Id of the job submitted.

statusUrl

String

-
This represents the status URL of the job that can be used to fetch the status of the submitted job.

Sample Success Response 

{
"result": true,
"requestId": "4fea0e53-4ef6-43ef-89b8-203b07ddab9e",
"data": {
"jobId": "d69faa51-919c-40a1-b747-c64a5ae69c0e",
"statusUrl": "v1.0/external/bulk/ingestion/async/status/d69faa51-919c-40a1-b747-c64a5ae69c0e"
}
}

People APIs - Bulk Async Process Status API

The People APIs - Bulk Async Process Status API helps to fetch detailed information on the status and can also retrieve the chunk file.

Method

GET

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/external/bulk/ingestion/async/status/<statusId>

Parameters

Parameter (*mandatory)

Data Type

Value (if any)

Description


chunkURL *

String


-
This represents the chunk URL that can be used to fetch the chunk response.

Sample Success Response

{
    "result": true,
    "requestId": "96a5941f-4130-4e80-a087-fddb6a9be7a5",
    "data": {
        "statusType": "COMPLETED",
        "response": {
            "status": "Completed",
            "successCount": 2,
            "failureCount": 0,
            "totalRecords": 2,
            "partialRecords": 0,
            "objectName": "person",
            "timeTaken": 0.795,
            "chunkDetails": [
                {
                    "chunkURL": "/external/bulk/ingestion/async/b00828df-d5a1-42a8-8b6e-1da09120e3b9/chunk/1/results"
                }
            ]
        }
    },
    "message": "COMPLETED"
}

Sample Failure Response

{
    "result": true,
    "requestId": "96a5941f-4130-4e80-a087-fddb6a9be7a5",
    "data": {
        "statusType": "COMPLETED",
        "response": {
            "status": "Completed",
            "successCount": 0,
            "failureCount": 2,
            "totalRecords": 2,
            "partialRecords": 0,
            "objectName": "person",
            "timeTaken": 0.795,
            "chunkDetails": [
                {
                    "chunkURL": "/external/bulk/ingestion/async/b00828df-d5a1-42a8-8b6e-1da09120e3b9/chunk/1/results"
                }
            ]
        }
    },
    "message": "COMPLETED"
}

People APIs- Bulk Async Process Chunk Result

This API helps to download the chunk file that is retrieved by the People APIs - Bulk Async Process Status API.

Method

GET

Endpoint URL

https://personapi.gainsightcloud.com/v1/peoplemgmt/v1.0/external/bulk/ingestion/async/<statusId>/chunk/1/results

Parameters

Parameter (*mandatory)

Data Type

Value (if any)

Description


chunkURL *

String

URL representing the end point that can be used to retrieve the response file. This represents the chunk URL using which the chunk response can be fetched.

Sample Success Response

{
  "successCount": 2,
  "totalCount": 2,
  "failureCount": 0,
  "partialSuccessCount": 0,
  "records": [
    {
      "record": {
        "companies": [
          {
            "relationships": [
              {
                "Role": "Admin",
                "Gsid": "1C03LJDGQOSVO8PI225VAOGS7UFCW3K7U2EN",
                "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                "Company_Person_ID": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
              },
              {
                "Role": "Admin",
                "Gsid": "1C03LJDGQOSVO8PI22259VTZ3DB57NNP15DW",
                "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
                "Company_Person_ID": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9H"
              }
            ],
            "Gsid": "1C01V3KWK4FX057IQ2XI81FUVKDK4TZI28QQ",
            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
            "Person_ID": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
            "IsPrimaryCompany": "true"
          }
        ],
        "Email": "johnsmith@gs.com",
        "Gsid": "1P04FFC950JNPDZ07X8XX5WGN88ZDUZVEY9F",
        "FirstName": "John",
        "LastName": "Smith",
        "Name": "John Smith",
        "Location": "California, US"
      },
      "messageId": "1",
      "rowNumber": 1,
      "operationStatus": "SUCCESS"
    },
    {
      "record": {
        "companies": [
          {
            "relationships": [],
            "Gsid": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
            "IsPrimaryCompany": "true"
          },
          {
            "relationships": [
              {
                "Role": "Executive Sponsor",
                "Gsid": "1C03LJDGQOSVO8PI224BTI5JU8URLQCGDTRM",
                "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
                "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
                "Company_Person_ID": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
              }
            ],
            "Gsid": "1C01V3KWK4FX057IQ2DUDXPKQ14JGMKRG0Y1",
            "Company_ID": "1P0287ONRQ5E7UYP6VE9PPP3AW3GOA131A5O",
            "Person_ID": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
            "IsPrimaryCompany": "true"
          }
        ],
        "Email": "stevenferguson@gs.com",
        "Gsid": "1P04FFC950JNPDZ07XBTN9510MYF48IAUG7S",
        "FirstName": "Steven",
        "LastName": "Ferguson",
        "Name": "Steven Ferguson",
        "Location": "California, US"
      },
      "messageId": "2",
      "rowNumber": 2,
      "operationStatus": "SUCCESS"
    }
  ]
}

Sample Failure Response

{
  "successCount": 0,
  "totalCount": 2,
  "failureCount": 2,
  "partialSuccessCount": 0,
  "records": [
    {
      "error": {
        "rowNum": 1,
        "details": [
          {
            "fieldName": "Email,Location",
            "values": {
              "Email,Location": {
                "Email": "jsmith@gs.com"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Email,Location",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID",
            "values": {
              "Company_ID,Person_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID,Relationship_ID",
            "values": {
              "Company_ID,Person_ID,Relationship_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID,Relationship_ID",
            "values": {
              "Company_ID,Person_ID,Relationship_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": null,
            "values": null,
            "errors": [
              {
                "message": "Row with the given resolution key already exists : {Company_ID=1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52, Person_ID=null, Relationship_ID=1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G}",
                "code": "GSOBJ_VCUSTOM1007"
              }
            ]
          }
        ],
        "record": null
      },
      "record": {
        "fff__gc": "true",
        "companies": [
          {
            "multi__gc": null,
            "relationships": [
              {
                "Role": "Admin",
                "Active": "true",
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Person_ID": null,
                "Company_Person_ID": null,
                "rp_checkbox_default__gc": "true",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
              },
              {
                "Role": "Admin",
                "Active": "true",
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Person_ID": null,
                "Company_Person_ID": null,
                "rp_checkbox_default__gc": "true",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L3198SKRYVPPDQ0YXPL9G"
              }
            ],
            "Active": "true",
            "cp_checkbox_default__gc": "true",
            "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
            "Person_ID": null,
            "IsPrimaryCompany": "true"
          }
        ],
        "Email": "jsmith@gs.com",
        "p_checkbox_default__gc": "true",
        "EmailOptOut": "false",
        "FirstName": "John",
        "LastName": "Smith",
        "Name": "John Smith"
      },
      "messageId": "1",
      "rowNumber": 1,
      "operationStatus": "FAILURE",
      "operationType": null
    },
    {
      "error": {
        "rowNum": 2,
        "details": [
          {
            "fieldName": "Email,Location",
            "values": {
              "Email,Location": {
                "Email": "sferguson@gainsight.com"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Email,Location",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID",
            "values": {
              "Company_ID,Person_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": null,
            "values": null,
            "errors": [
              {
                "message": "Row with the given resolution key already exists : {Company_ID=1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52, Person_ID=null}",
                "code": "GSOBJ_VCUSTOM1007"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID",
            "values": {
              "Company_ID,Person_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJME2XUU84B6OTTHEXDH6"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          },
          {
            "fieldName": "Company_ID,Person_ID,Relationship_ID",
            "values": {
              "Company_ID,Person_ID,Relationship_ID": {
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
              }
            },
            "errors": [
              {
                "message": "Resolution key value is null or empty : Person_ID",
                "code": "GSOBJ_VCUSTOM1012"
              }
            ]
          }
        ],
        "record": null
      },
      "record": {
        "fff__gc": "true",
        "companies": [
          {
            "multi__gc": null,
            "relationships": [],
            "Active": "true",
            "cp_checkbox_default__gc": "true",
            "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
            "Person_ID": null,
            "IsPrimaryCompany": "true"
          },
          {
            "multi__gc": null,
            "relationships": [
              {
                "Role": "Executive Sponsor",
                "Active": "true",
                "Company_ID": "1P022A6Z2DWEK48YJM70JL88EWWA8Y0MET52",
                "Person_ID": null,
                "Company_Person_ID": null,
                "rp_checkbox_default__gc": "true",
                "IsPrimaryCompany": "true",
                "Relationship_ID": "1P0589D9GZXBR11L31AIRD85YY0HG8XT0O37"
              }
            ],
            "Active": "true",
            "cp_checkbox_default__gc": "true",
            "Company_ID": "1P022A6Z2DWEK48YJME2XUU84B6OTTHEXDH6",
            "Person_ID": null,
            "IsPrimaryCompany": "true"
          }
        ],
        "Email": "sferguson@gainsight.com",
        "p_checkbox_default__gc": "true",
        "EmailOptOut": "false",
        "FirstName": "Steven",
        "LastName": "Ferguson",
        "Name": "Steven Ferguson"
      },
      "messageId": "2",
      "rowNumber": 2,
      "operationStatus": "FAILURE",
      "operationType": null
    }
  ],
  "outPutFilePath": null
}
  • Was this article helpful?