Skip to main content
Gainsight Inc.

Timeline APIs

  1. Last updated
  2. Save as PDF 
Gainsight NXT

This article supports Gainsight NXT, the next evolution of the Customer Success platform. If you are using Gainsight CS Salesforce Edition, you can find supporting documentation by visiting the home page, and selecting CS > Salesforce Edition.

Not sure what your team is using? Click here.

 

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

Response header attribute x-ratelimit-limit shows the limit per hour and per day.

Below is the sample response header for bulk API call:

extapiheaders.png

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

(*mandatory)

Data Type

Values

Description
ContextName* String

Company

Relationship

 A String value that contains the Context Name of an Activity, it can either be Company or Relationship. It describes whether the Activity was created on a Company or on a Relationship.
ExternalId (Record Id)* String -

A String value that contains the Record id received from the client. It is unique for an activity. In case duplicate Ids are received, the records are rejected.
Author* String - A String value that contains the name of the owner of an Activity

 

Subject*

 String - A String value that contains the subject of an Activity.The character limit of 255
Notes* String - A  String value that contains Html formatted notes from the Activity. The character limit is 32000 for plain text
Activity Date DateTime -

A DateTime value. 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 - A String value that contains the type of Activity, provide activity form Id or name of the Activity.
CompanyName* String - A String value that contains the name of the Company
RelationshipName String - A String value that contains 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 - A String value that contains the Relationship type Id . It is mandatory in case the Activity is created on a  Relationship Context.

internalAttendees

 List - A List value that contains a list of internal users
externalAttendees List   A List value that contains a 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"
        }
    }
}

Note: 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

(*mandatory)

Data Type

Values

Description
ContextName* String

Company

Relationship

 A String value that contains the Context Name of an Activity, it can either be Company or Relationship. It describes whether the Activity was created on a Company or on a Relationship.
ExternalId (Record Id)* String -

A String value that contains the Record id received from the client. It is unique for an activity. In case duplicate Ids are received, the records are rejected.
Author* String - A String value that contains the name of the owner of an Activity

 

Subject*

 String - A String value that contains the subject of an Activity.The character limit of 255
Notes* String - A  String value that contains Html formatted notes from the Activity. The character limit is 32000 for plain text
Activity Date DateTime -

A DateTime value. 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 - A String value that contains the type of Activity, provide activity form Id or name of the Activity.
CompanyName* String - A String value that contains the name of the Company
RelationshipName String - A String value that contains 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 - A String value that contains the Relationship type Id . It is mandatory in case the Activity is created on a  Relationship Context.

internalAttendees

 List - A List value that contains a list of internal users
externalAttendees List   A List value that contains a list of  external users

Note: Attachments and Linked objects are not supported.

Sample Response


{
    "data": {
      "jobId": "e0413b58-b38c-47e9-a303-9a8f80824fbb",
       "jobAbortEndPoint": "ant/es/job/abort/e0413b58-b38c-47e9-a303-9a8f80824fbb",
       "jobStatusEndPoint": "ant/es/job/status/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 four status states- COMPLETED, INPROGRESS,  SUBMITTED AND ABORTED.

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

(*mandatory)

Data Type

Values

Description
job_id* String

-

 A String 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/bulk?identifier=<identifier>

IMPORTANT: The value of the query parameter identifier can be externalid or activityid.

Sample request URLs for update API:

  • Update using external Id: 

v1/ant/es/activity/bulk?identifier=externalid

  • Update using activity Id:

v1/ant/es/activity/bulk?identifier=activityid

Sample Request 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

(*mandatory)

Data Type

Values

Description

 

ExternalId*

String

 -

This String value is mandatory if the value of the query parameter identifier is externalid.

Gsid* <activityId>

String

 -

This  String value is mandatory if the value of the query parameter identifier is activityid or when no query parameter is provided.

Subject*

String

 -

A String value that contains the subject of the Activity with a character limit of 255

Notes*

String

 -

A String value that contains Html formatted notes from the Activity with a character limit of 32000 for plain text

ActivityTypeId* or TypeName

String

 -

A String value that contains 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 Request 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 Request Body

{
"filter": {
  "dateFilter": {
    "dateLiteral": "CUSTOM",
    "values": [
      "2022-06-21T06:39:00.000-07:00",
       "2022-06-22T06:39:00.000-07:00"     
       ]
  }
}
}

Parameters

Parameter

(*mandatory)

Data Type

Values

Description

dateLiteral*

 

 String - A String value that provides a date range to fetch the list of deleted activities.
values List - A List  that contains 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

POST

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"
  }
}

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
}

Abort API

This API helps you abort the submitted bulk insert/update records job. The job will be aborted only if the job is in “SUBMITTED” status, the job which is already started cannot be aborted. 

Note: It is recommended to check the job status using status API before abort API is triggered.

Method 

PUT

Endpoint URL


v1/ant/es/job/abort/<job_id>

Sample Success Response


{
    "data": {
        "message": "Job has been aborted",
        "status": "ABORTED"
    },
    "result": true,
    "message": null,
    "additionalInfo": null
}

Parameters

Parameter

(*mandatory)

Data Type

Values

Description
job_id* String

-

 A String value from the response of the bulk save/update API that can be used to check the processed record

Sample Failure Response

This response is received when the job cannot be aborted due to technical issues.


 
   "data": {
       "message": "Job could not be aborted",
       "status": "COMPLETED"
   },
   "result": true,
   "message": null,
   "additionalInfo": 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

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    1. Bulk Activity Save API
    2. Fetch Delete API
    3. Single Activity Save API
    4. Timeline API
    5. Update API