Skip to main content
Gainsight Inc.

Timeline APIs

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

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

12 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 (Company Context)



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

Sample Request Body (Relationship Context)

The following example helps adding an activity at the relationship level. This example also includes how to look up when using multi-column lookup. For example, if the same relationship name iexists for more than one company, we can add one more lookup column(company name) to find the exact matching record. In this example,  the "companyName":"CompanyId__gr.Name" is added in “GsRelationshipId” lookup will help to find the exact match.



{
    "records": [
         {
            "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"]
            
        }
    ],
    "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",
              "companyName":"CompanyId__gr.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"
        }
    }
}

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 of internal users in array or comma separated users.
externalAttendees List   A list of external users in array or comma separated 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 of internal users in array or comma separated users.
externalAttendees List   A list of external users in array or comma separated 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. Following are the possible status states:

  • COMPLETED
  • IN_PROGRESS
  • SUBMITTED
  • FAILED
  • NOT_STARTED
  • 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

{
    "result": true,
    "data": {
        "jobId": "a65370d2-43d0-4b9d-b894-332bf536d148",
        "status": "COMPLETED",
        "failedCount": 0,
        "successCount": 2,
        "failures": {},
        "successes": {
            "18f0383a1e404d7ba52361bb7370d7gf": [
                {
                    "activityId": "1I004SG7RDV06L1HFJCRQ3IQPXFW7GN5I6L5"
                }
            ],
            "21f0383a1e404d7ba52361bb7370d7de534521258789": [
                {
                    "activityId": "1I004SG7RDV06L1HFJZENMQLYM2BT86H82HW"
                }
            ]
        }
    },
    "message": null,
    "errorCode": null,
    "requestId": "08c24fdb-37fa-4bae-86ce-e8e05c9b1927"
}

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
}

Single Update API

This API updates a single activity provided in the request body. The record can either be identified by externalId or by activityId.

Method 

PUT

Endpoint URL

v1/ant/es/activity?identifier=<identifier>

Note: The value of the query parameter identifier can be externalid or activityid or gsid. If more than one record is provided in the request body, only the first record is updated.

Sample request urls for single update API: 

  • Update using external API
v1/ant/es/activity?identifier=externalid

  • Update using activity Id

v1/ant/es/activity?identifier=activityid

  • Update using activity Id

v1/ant/es/activity?identifier=gsid
{
    "records": [
        { 
            "ActivityTypeId": "163ca3c2-06c1-4507-ba8a-ceba6ae0004e",
            "Gsid": "1I004SG7RDV06L1HFJ1H1ZBCCOH5GJH3VD4L",
            "Subject": "Updated subject",
            "Notes": "Updated notes",
            "companyName": "AAR Corp Hardware Abscoa Division",
            "internalAttendees": [
              "smitha test",
              "Sandeep Kumar",
              "Mike o'brien"
            ]
        }
    ],
    "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 gsid 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

 - Html formatted notes from the Activity with a character limit of 32000 for plain text
ExternalId String   This parameter is mandatory if the value of the query parametre identifier is externalid.
Gsid <activityId> String   This parameter is mandatory if the value of the query parameter identifier is activityid or gsid or when no query parametre is provided.

Sample Response

{
   "data": {
       "failures": {},
       "successes": {
           "1I004SG7RDV06L1HFJ1H1ZBCCOH5GJH3VD4L": [
               {
                   "activityId": "1I004SG7RDV06L1HFJ1H1ZBCCOH5GJH3VD4L"
               }
           ]
       }
   },
   "result": true,
   "message": null,
   "additionalInfo": null}

Bulk 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 or gsid.

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

  • Update using activity Id:

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

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


[
   "{{ActivityId1}}",
   "{{ActivityId2}}"
]

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

GS_TL_10_0301

Invalid data type for key `Notes`. Expected String.

Invalid data type provided for “Notes” field

200

GS_TL_10_0301

Invalid data type for key `Ant__Tag__c`. Expected String Array.

Invalid data type provided for multi picklist field

200

GS_TL_10_0301

Invalid data type for key `Ant__Yes__c`. Expected Boolean (true/false).

Invalid data type provided for checkbox/boolean field

200

GS_TL_10_0301

Invalid data type for key `DurationInMins`. Expected Integer.

Invalid datatype provided for Number field

200

GS_TL_10_0301

Invalid data type for key `ActivityDate`. Expected ISO 8601 Date Time String.

Invalid data type provided for date type fields

200

GS_TL_10_0301

Invalid data type for key `Ant__pi__c`. Expected Number with max precision 2.

Invalid data type provided for decimal number

200

Sample  Data for Different Data Types

Field type

Allowed field formats

Comment

Boolean

Supported values are true or false

“Ant__Yes__c”: true

“Ant__Yes__c”: false

String

Text (specify the text enclosed in double quotes)

“Subject”: “this is subject”

Picklist

Picklist gsid or picklist label can be provided in double quotes

“Ant__Country__c”:”USA”

“Ant__Country__c”:”1I006JE181N2GLVUEFVT8U87OIHXTL743DJ8”

Multipicklist


Semicolon separated string value

 

OR

 

Array of strings

- String can be gsid or label

“Ant__Tag__c”:“Tag1;Tag2;Tag3”

“Ant__Tag__c”:“1I006JE181N2GLVUEFVT8U87OIHXTL743DJ8;1I006JE181N2GLVUEFVT8U87OIHXTL743DJ43”

 

 

“Ant__Tag__c”: [“Tag1”,”Tag2”, “Tag3”]

“Ant__Tag__c”: [“1I006JE181N2GLVUEFVT8U87OIHXTL743DJ43”,”1I006JE181N2GLVUEFVT8U87OIHXTL743DJ8”]

Number

Integer or floating numbers can be provided

"Ant__CustomNumber__c": 25

 

"Ant__CustomNumber__c": 25

Date

Date in ISO 860 format(“yyyy-MM-dd”)

"Ant__Cdate__c": "2023-03-31"

DateTime

Date time in ISO 8601 format (`yyyy-MM-dd'T'HH:mm:ss.SSSXXX’ )

"Ant__Cdatetime__c" : "2022-07-31T06:36:00.000-07:00"

InternalAttendees

Comma separated User IDs in string format

 

Array of UserIds




 

Comma separated emailIds/Names based on the lookup provided

 

Array of strings (either email/name) based on lookup provided

"InternalAttendees": "1P01E6LDGUSKRJ52MKPXS3Y5BV48V65FMIBN,1P01E6LDGUSKRJ52MKPXS3Y5BV48V65FMABC"

 

"InternalAttendees": ["1P01E6LDGUSKRJ52MKPXS3Y5BV48V65FMIBN”,”1P01E6LDGUSKRJ52MKPXS3Y5BV48V65FMABC"]

 

"internalAttendees":    "hysty@gainsight.com,seka@gainsight.com"



 

"internalAttendees": [

      "hysty@gainsight.com",

      "seka@gainsight.com"

]

ExternalAttendees

Comma separated company-person IDs in string format

 

Array of CompanypersonIds



 

Comma separated company person emailIds/Names based on the lookup provided

 

Array of strings (either email/name) based on lookup provided

"ExternalAttendees": "1C01E6LDGUSKRJ52MKPXS3Y5BV48V65FMIBN,1C01E6LDGUSKRJ52MKPXS3Y5BV48V65FMABC"

 

"ExternalAttendees": ["1C01E6LDGUSKRJ52MKPXS3Y5BV48V65FMIBN”,”1C01E6LDGUSKRJ52MKPXS3Y5BV48V65FMABC"]

 

"externalAttendees":    "hysty@abc.com,seka@xyz.com"




 

"externalAttendees": [

      "hysty@abc.com",

      "seka@xyz.com"

]

Duration standard field

Field name is expected to be “DurationInMins”

“DurationInMins”: 50

Notes: 

  • Left side parameter name should match with the exact fieldName, otherwise the value will be ignored while inserting or updating.
  • Field values will be stored even if the fields are not available in the activity form.
  • When providing GSIDs for internal or external attendees, make sure the fieldname is correct (“InternalAttendees”, “ExternalAttendees”).
  • Context for which activity is inserted , cannot be updated through APIs.
  • Audit fields (CreatedBy, CreatedAt, ModifiedBy, ModifiedAt) field cannot be updated through APIs.
  • ExternalId and GSID cannot be updated though APIs, because they will be used as identifiers to update the records.
  • GSIDs provided as part of payload are not validated. For example, "AuthorId" , "GsCompanyId", "GsRelationshipTypeId" are not validated against database.
  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