Skip to main content
Gainsight Inc.

Timeline APIs

  1. Last updated
  2. Save as PDF
This article explains how to create, update and delete Timeline activities using 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

 

  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