Timeline APIs
This article explains how to create, update and delete Timeline activities using APIs.
Introduction
Timeline APIs help you create, update, and delete Timeline Activities. Timeline APIs are external APIs that help you integrate with other CRM to get data into Gainsight.
Authorization
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. For more information on how 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 have to pass the access key as part of the request header “accesskey” for all of your API requests into Gainsight.
Note: The AccessKey does not expire.
Headers
Key |
Value |
---|---|
Accesskey |
For more information on how to generate an access key, refer to the Authorization section. |
Content Type |
JSON |
Throttling Limits
API |
Rate Limit |
---|---|
Singular insert |
200 calls per minute |
Bulk insert |
4 calls for an hour/ 80MB size payload per call |
Single Activity Save API
This API helps you save an Activity to Timeline.
Method
POST
Endpoint URL
v1/ant/es/activity
Sample Request Body
{ "records": [ { "ContextName": "Company", "TypeName": "Update", "ExternalId": "16f0383a1e404d7ba52361bb7370d7de", "Subject": "External API demo 1", "Notes": "notes for the activity", "ActivityDate": "2022-07-01T06:36:00.000-07:00", "Author": "testuser@gainsight.com", "companyName": "Tech systems ABC Ltd", "internalAttendees": [ "hysty@gainsight.com", "seka@gainsight.com" ] } ], "lookups": { "AuthorId": { "fields": { "Author": "Email" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "GsCompanyId": { "fields": { "companyName": "Name" }, "lookupField": "Gsid", "objectName": "Company", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "InternalAttendees": { "fields": { "internalAttendees": "Email" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "MARKASERROR" } } }
Parameters
Parameter (mention if mandatory or optional)* |
Data Type | Values (if any) | Description |
---|---|---|---|
ContextName* | String |
Company Relationship |
The ContextName of an Activity is either Company or Relationship. It describes whether the Activity was created on a Company or on a Relationship. |
ExternalId (Record Id)* | String | - |
Record id received from the client. It is unique for an activity. In case duplicate Ids are received, the records are rejected. |
Author* | String | - | Owner of Activity |
Subject* |
String | - | Subject of the Activity with a character limit of 255 |
Notes* | String | - | Html formatted notes from the Activity with a character limit of 32000 for plain text |
Activity Date | DateTime | - |
The format for this parameter is: ISO 8601 format - `yyyy-MM-dd'T'HH:mm:ss.SSSXXX’ The current date in UTC is added by default if no value is provided. |
ActivityTypeId* or TypeName* | String | - | The type of Activity, provide activity form Id or name of the Activity. |
CompanyName* | String | - | The name of the Company |
RelationshipName | String | - | The name of the Relationship if the Activity is created on a Relationship. This parameter is mandatory when the Activity is created on a Relationship context. |
GsRelationshipTypeId | String | - | Relationship type Id is mandatory in case the Activity is created on a Relationship Context. |
internalAttendees |
List | - | List of internal users |
externalAttendees | List | List of external users |
Note: Attachments and Linked objects are not supported.
Sample Success Response
{ "data": { "failures": {}, "success": { "16f0383a1e404d7ba52361bb7370d7de": [ { "activityId": "1I004SG7RDV06L1HFJODBJK5F3TG0R4KAWHY" } ] }, "result": true, "message": null, "additionalInfo": null }
Sample Failure Response
{ "data": { "failures": { "16f0383a1e404d7ba52361bb7370d7de": [ { "errorCode": "GS_TL_10_0206", "errorMessage": "Activity context name for key 'ContextName' missing" } ] }, "success": {} }, "result": true, "message": null, "additionalInfo": null }
Bulk Activity Save API
This API helps you save multiple Activities to Timeline. Maximum allowed size of the payload is 80MB.
Method
POST
Endpoint URL
/v1/ant/es/activity/bulk
Sample Request Body
{ "records": [ { "Author":"abc@gainsight.com", "ContextName": "Company", "TypeName": "Meeting", "ExternalId": "16f0383a1e404d7ba52361bb7370d7de", "Subject": "New activity of company context", "Notes": "notes for activity", "companyName": "AAR Corp Hardware Abscoa Division", "internalAttendees": [ "Katy N", "Peter L", "Mike o'brien" ], "externalAttendees": [ "tammy aar2", "swapna AAR"] }, { "Author": "abc@gainsight.com", "ContextName": "Relationship", "TypeName": "newrelactivity", "ExternalId": "18f0383a1e404d7ba52361bb7370d7gf", "Subject": "New activity of Relationship context custom activity type test rollup settings", "Notes": "Notes for custom activity", "companyName": "AAR Corp Hardware Abscoa Division", "GsRelationshipTypeId":"1P06GOGHZYYQJQ9HMNK0TR0XP2Z29VGJ53IL", "RelationshipName": "Gainsight Desktop", "Ant__CustomDateField__c": "2022-06-08", "Ant__Publish__c": "publish field", "Ant__Remarks__c": "remarks field", "Ant__date_ttimee__c": "2022-06-08T21:09:20.000-07:00", "internalAttendees": [ "Trail35 tr" ], "externalAttendees": [ "tammy aar2", "swapna AAR", "Jyothi aar"] }, { "ContextName": "Company", "TypeName": "Update", "ExternalId": "21f0383a1e404d7ba52361bb7370d7de534521258789", "Subject": "External API demo 1", "Notes": "notes for the activity", "ActivityDate": "2022-07-01T06:36:00.000-07:00", "Author": "testuser@gainsight.com", "companyName": "Tech systems ABC Ltd", } ], "lookups": { "AuthorId": { "fields": { "Author": "Email" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "GsCompanyId": { "fields": { "companyName": "Name" }, "lookupField": "Gsid", "objectName": "Company", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "GsRelationshipId": { "fields": { "RelationshipName": "Name" }, "lookupField": "Gsid", "objectName": "Relationship", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "InternalAttendees": { "fields": { "internalAttendees": "Name" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "FIRSTMATCH" }, "ExternalAttendees": { "fields": { "externalAttendees": "Person_ID__gr.Name", "GsCompanyId": "Company_ID" }, "lookupField": "Gsid", "objectName": "Company_Person", "multiMatchOption": "FIRSTMATCH" } } } e: Custom fields are also supported. Values for the custom fields can be updated using field names starting with “Ant_<fieldName>” as mentioned in the above sample.
Parameters
Parameter (mention if mandatory or optional)* |
Data Type | Values (if any) | Description |
---|---|---|---|
ContextName* | String |
Company Relationship |
The Context Name of an Activity is either Company or Relationship. It describes whether the Activity was created on a Company or on a Relationship. |
ExternalId (Record Id)* | String | - |
Record id received from the client. It is unique for an activity. In case duplicate Ids are received, the records are rejected. |
Author* | String | - | Owner of Activity |
Subject* |
String | - | Subject of the Activity with a character limit of 255 |
Notes* | String | - | Html formatted notes from the Activity with a character limit of 32000 for plain text |
Activity Date | DateTime | - |
The format for this parameter is: ISO 8601 format - `yyyy-MM-dd'T'HH:mm:ss.sssZ’ The current date in UTC is added by default if no value is provided. |
ActivityTypeId* or TypeName* | String | - | The type of Activity, provide activity form Id or name of the Activity. |
CompanyName* | String | - | The name of the Company |
RelationshipName | String | - | The name of the Relationship if the Activity is created on a Relationship. This parameter is mandatory when the Activity is created on a Relationship context. |
GsRelationshipTypeId | String | - | Relationship type Id is mandatory in case the Activity is created on a Relationship Context. |
internalAttendees |
List | - | List of internal users |
externalAttendees | List | List of company persons |
Note: Attachments and Linked objects are not supported.
Sample Response
{ "data": { "jobId": "e0413b58-b38c-47e9-a303-9a8f80824fbb", "status": "SUBMITTED" }, "result": true, "message": null, "additionalInfo": null }
Get Status API
This API helps you check the status of submitted bulk records. There are three status states- COMPLETED, INPROGRESS, and SUBMITTED
Note : jobId from the response of the Bulk Save or Update API can be used to check the status of the submitted records.
Method
GET
Endpoint URL
v1/ant/es/job/status/<job_id>
Sample Success Response
{ "data": { "jobId": "30f5134d-dbd6-4ed8-af04-4a266a53b63d", "status": "COMPLETED", "failedCount": 2, "successCount": 1, "failures": { "21f0383a1e404d7ba52361bb7370d7de534521258789": [{ "errorCode": "GS_TL_10_0213", "errorMessage": "Context id is missing" }, { "errorCode": "GS_TL_10_0214", "errorMessage": "Subject id is missing" } ], "16f0383a1e404d7ba52361bb7370d7de": [{ "errorCode": "GS_TL_10_0214", "errorMessage": "Subject is missing" }] }, "successes": { "18f0383a1e404d7ba52361bb7370d7gf": [{ "activityId": "1I004SG7RDV06L1HFJODBJK5F3TG0R4KAWHZ" }] } }, "result": true, "message": null, "additionalInfo": null }
Parameters
Parameter (mention if mandatory or optional)* |
Data Type |
Description |
---|---|---|
job_id* | String |
jobId from the response of the bulk save/update API can be used to check the processed record |
Sample Failure Response
{ "data": { "jobId": "c7a45677-191f-4e9f-acf7-b7b2192c1c8f", "status": "COMPLETED", "failedCount": 1, "successCount": 4, "failures": { "ERecord333013": [ "No record found for GsRelationshipId" ] }, "successes": { "ERecord222012": [ "1I004SG7RDV06L1HFJFA73MAQVULEQ09WZ4F" ], "ERecord111011": [ "1I004SG7RDV06L1HFJNFOXJRYWAQGD2I9SVD" ], "ERecord555015": [ "1I004SG7RDV06L1HFJ6VRST8FJJ2U50T11BF" ], "ERecord444024": [ "1I004SG7RDV06L1HFJLF2T9CKE5IYOKCBPC9" ] } }, "result": true, "message": null, "additionalInfo": null }
Sample Failure Response Due to Technical Issues
This response is received when the job fails due to technical issues.
{ "data": { "jobId": "b573e85a-9826-4c04-8c20-05963b95033d", "status": "FAILED", "failedCount": 0, "successCount": 0, "failures": null, "successes": null }, "result": true, "message": null, "additionalInfo": null }
Sample Failure Response due to Incorrect Job Id Response
{ "data": null, "result": false, "message": "Incorrect job id", "additionalInfo": null }
Update API
This API updates Activities listed in the request body. The records can either be identified by externalId or by activityId.
Note: While updating the bulk records, the parameter set you are trying to update should be the same for all the records per activity type.
Method
PUT
Endpoint URL
v1/ant/es/activity?identifier=<identifier>
Note: The value of the query parameter identifier can be externalid or activityid.
Sample Body
{ "records": [ { "ActivityTypeId": "163ca3c2-06c1-4507-ba8a-ceba6ae0004e", "ExternalId": "16f0383a1e404d7ba52361bb7370d7de", "Subject": "Updated subject", "Notes": "Updated notes", "companyName": "AAR Corp Hardware Abscoa Division", "internalAttendees": [ "smitha test", "Sandeep Kumar", "Mike o'brien" ] }, { "ActivityTypeId": "a7a66ff2-c0de-4bd2-b607-ea5eb198b961", "ExternalId": "18f0383a1e404d7ba52361bb7370d7gf", "Subject": "test rel update", "Notes": "Notes for custom rel activity - invalid activity id, but valid external id", "companyName": "AAR Corp Hardware Abscoa Division", "GsRelationshipTypeId":"1P06GOGHZYYQJQ9HMNK0TR0XP2Z29VGJ53IL", "GsRelationshipId":"1P05H693E70AQ4W1X360SOIR73VW953CLPYD", } ], "lookups": { "AuthorId": { "fields": { "Author": "Email" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "GsCompanyId": { "fields": { "companyName": "Name" }, "lookupField": "Gsid", "objectName": "Company", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "GsRelationshipId": { "fields": { "RelationshipName": "Name" }, "lookupField": "Gsid", "objectName": "Relationship", "multiMatchOption": "FIRSTMATCH", "onNoMatch": "ERROR" }, "InternalAttendees": { "fields": { "internalAttendees": "Name" }, "lookupField": "Gsid", "objectName": "GsUser", "multiMatchOption": "FIRSTMATCH" } } }
Parameters
Parameter (mention if mandatory or optional)* |
Data Type |
Description |
---|---|---|
ExternalId* |
String |
This parameter is mandatory if the value of the query parameter identifier is externalid. |
Gsid* <activityId> |
String |
This parameter is mandatory if the value of the query parameter identifier is activityid or when no query parameter is provided. |
Subject* |
String |
Subject of the Activity with a character limit of 255 |
Notes* |
String |
Html formatted notes from the Activity with a character limit of 32000 for plain text |
ActivityTypeId* or TypeName |
String |
The type of Activity, provide activity form Id or name of the Activity. |
Sample Response
{ "data": { "jobId": "e0413b58-b38c-47e9-a303-9a8f80824fbb", "status": "SUBMITTED" }, "result": true, "message": null, "additionalInfo": null }
Delete API
This API deletes Activities listed in the request body. The records will be identified by activityId.
Method
DELETE
Endpoint URL
v1/ant/es/activity
Sample Body
[ "1I004SG7RDV06L1HFJQV0XO6SLZAD1TEXL4E", "1I004SG7RDV06L1HFJONKLZEUGLR8J6S4IZ0" ]
Sample Response Body
[ "1I004SG7RDV06L1HFJQV0XO6SLZAD1TEXL4E", "1I004SG7RDV06L1HFJONKLZEUGLR8J6S4IZ0" ]
Fetch Deleted API
This API helps you retrieve the list of deleted Activities in the given timestamp range. Timestamp should be in ISO 8601 format , i.e. ”yyyy-MM-dd'T'HH:mm:ss.SSSXXX”.
Method
POST
Endpoint URL
v1/ant/es/activity/deleted
Sample Body
{ "filter": { "dateFilter": { "dateLiteral": "CUSTOM", "values": [ "2022-06-21T06:39:00.000-07:00", "2022-06-22T06:39:00.000-07:00" ] } } }
Parameters
Parameter (mention if mandatory or optional)* |
Data Type |
Description |
---|---|---|
dateLiteral*
|
String | Provide a date range to fetch the list of deleted activities. |
values | List | Start and end timestamps in ISO 8601 format yyyy-MM-dd'T'HH:mm:ss.SSSXXX |
Read API
This API lets you read the inserted activity record details.
Method
GET
Endpoint URL
gainsightdomain/v1/data/objects/query/activity_timeline
Sample Request Body
{ "select": [ "contextname", "GsRelationshipId", "GsCompanyId", "AuthorId", "InternalAttendees", "ExternalAttendees", "Ant__CustomNumber__c", "internalAttendees", "Ant__CustomText__c", "Ant__CustomCheckbox__c" ], "where": { "conditions": [ { "name": "ExternalId", "alias": "A", "value": [ "01c43677-5cc8-4309-88e8-d929024abdc1" ], "operator": "EQ" } ], "expression": "A" } }
Parameters
Parameter (mention if mandatory or optional)* |
Description |
---|---|
API Key
|
The API Access key received from Gainsight. For more information on how to generate an access key, refer to the Authorization section. |
Read Record JSON | This is the JSON that represents the entire query criteria. A sample JSON is shown in the sample request body. |
Sample Response Body
{ "result": true, "errorCode": null, "errorDesc": null, "requestId": "7814d30f-a17b-44ea-9c03-fd3fdcd4b746", "data": { "records": [ { "contextname": "Relationship", "GsRelationshipId": "1P052FF55UXKNWG3E7P0ILJL8B53QH9SRV51", "GsCompanyId": "1P02G76AI7KS5P406VQB2PSRVO1OD4EC163O", "AuthorId": "1P01XWZAME0GW3RXT8L70ZWAX94WHD41SS7U", "ExternalAttendees": null, "Ant__CustomNumber__c": 300, "internalAttendees": "abhilash", "Ant__CustomText__c": "custom text field", "Ant__CustomCheckbox__c": true } ] }, "message": null }
Error Codes
Error code
|
Error Message
|
Reason |
HTTP Status Code |
---|---|---|---|
GS_TL_10_0202 | External Id for key `ExternalId` missing | External Id key is not provided in the request | 200 |
GS_TL_10_0110 | Activity identifier key not provided | Activity identifier key is not provided | 200 |
GS_TL_10_0203 | ActivityTypeId missing | Activity Type ID is not provided in the request | 200 |
GS_TL_10_0107 | Activity with same External Id exists |
A record exists with the given ExternalId. |
200 |
GS_TL_10_0108 | Multiple records with same External Id found. First taken | Bulk insert payload has multiple records with the same external id. | 200 |
GS_TL_10_0211 | Activity context name for key `ContextName` missing | ContextName is not provided in the request. | 200 |
GS_TL_10_0214 | Relationship gsid for key `GsRelationshipId` is missing | GsRelationshipId is not provided in the request | 200 |
GS_TL_10_0215 | Relationship Type gsid for key `GsRelationshipTypeId` is missing | GsRelatioshipTypeId key is missing in payload | 200 |
GS_TL_10_0222 | Date Time is expected to be expressed according to ISO 8601 - `yyyy-MM-dd'T'HH:mm:ssZ`. Field Ant__date_ttimee__c | Invalid date-time format | 200 |
GS_TL_10_0223 | Date is expected to be expressed according to ISO 8601 - `yyyy-MM-dd`. Field Ant__CustomDateField__c | Invalid date format | 200 |