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.
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:
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.
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:
- You can also pass only Relationship ID (without Company ID) with person details instead of lookup details as explained in the section, Request Body - API with Association IDs.
- You can also pass only Relationship Lookup details without person details as explained in the section, Upsert API with only Company and Relationship Lookup.
- You can also insert or update multiple person records with only Relationship IDs or Lookup details as explained in the section, Upsert Person API with Association IDs or Lookup Details.
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.
Request Body
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
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 }