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

API	Rate Limit
Singular insert	200 calls per minute
Bulk insert	12 calls for an hour/ 80MB size payload per call

Activity Fields Reference

This helps you to understand all the Activity fields applicable and how to use them in API.

Required Fields (INSERT)

API Field Name	Type	Description
ExternalId	String	Your unique identifier for this activity. Used as the idempotency key on insert and as the match key on update when identifier=externalid. Must be unique within the request batch and across all previously inserted records for this tenant.
Author	String	Email address of the activity author. Resolved to a Gainsight User GSID via the AuthorId lookup.
ContextName	String	Activity context type. Valid values: Company, Relationship, CTA, SuccessPlan, Scorecard, ScorecardMeasure, Milestone.
TypeName	String	Activity type name (e.g., Meeting, Email, Phone Call). Must exactly match an existing Activity Type in your tenant. Use GET /es/forms to discover valid values. Alternatively provide ActivityTypeId.
Subject	String	Activity subject line. The maximum limit is 255 characters.
Notes	String	Activity body or notes. Accepts plain text or HTML. Max ~131,000 characters (plain text).
ActivityDate	String	ISO 8601 datetime. Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ. Example: 2026-04-14T10:30:00.000+0000.
(context ID field)	String	One of companyName, GsRelationshipId, ContextId, etc. — depends on ContextName.

Either TypeName or ActivityTypeId must be provided. If both are specified, ActivityTypeId takes precedence.

Optional Fields

API Field Name	Type	Description
ActivityTypeId	String	GSID of the activity type. Use instead of TypeName when you already have the GSID.
ExternalSource	String	Label for the source system (example, Salesforce, Zendesk, HubSpot). Stored as free text.
DurationInMins	Number	Duration of the activity in minutes. Numeric only.
Trackers	String	Comma-separated list of multi-picklist tracker values. Values must match defined picklist options exactly (case-sensitive).
MediaUrl	String	URL to a recording or file associated with the activity (example, Zoom recording link).
ReportingCategory	String	Category label used in reporting aggregations.
ActivitySentiment	String	Sentiment of the activity. Valid values depend on tenant configuration.

Custom Fields

Custom activity fields use the prefix Ant_ followed by the field's API name:

"Ant_ContractValue": 125000,
"Ant_MeetingType": "Executive",
"Ant_FollowUpDate": "2026-05-01"

Data Type	Format
Text	Plain string
Number	Numeric (no quotes)
Date	yyyy-MM-dd (date only, no time component)
DateTime	yyyy-MM-dd'T'HH:mm:ss.SSSZ
Boolean	true / false

Context Types

ContextName determines which additional identifier field(s) are required in the record.

ContextName	Required Field(s)	How to Provide
Company	GsCompanyId	Pass companyName + GsCompanyId lookup (resolves name → GSID), or pass the Company GSID directly as GsCompanyId
Relationship	GsRelationshipId, GsRelationshipTypeId	Pass both GSIDs directly
CTA	ContextId	Pass the CTA GSID directly
SuccessPlan	ContextId	Pass the Success Plan GSID directly
Scorecard	ScorecardId	Pass the scorecard GSID, or provide Scorecard (name)
ScorecardMeasure	ScorecardMeasureId or ContextId	Pass the measure GSID
Milestone	MilestoneType	Pass the milestone type label string. Use GET /es/milestones to list valid values.

Company Context

There are two ways to identify a Company:

Option A: Lookup by name
Option B: Direct GSID

Option A — Lookup by name (most common)

Pass the company's display name as companyName and configure a GsCompanyId lookup. The API resolves the name to a GSID automatically before saving.

{
 "records": [{ "companyName": "AlphaCorp", ...other fields... }],
 "lookups": {
   "GsCompanyId": {
     "objectName": "Company",
     "fields": { "companyName": "Name" },
     "lookupField": "Gsid",
     "multiMatchOption": "FIRSTMATCH",
     "onNoMatch": "ERROR"
   }
 }
}

Option B — Direct GSID

If you already have the Gainsight Company GSID, pass it directly as GsCompanyId and omit the lookup entry.

{
 "records": [{ "GsCompanyId": "5f3a2b1c9d8e7f4a3b2c1d0e", ...other fields... }],
 "lookups": {}
}

companyName is the lookup input field — it is NOT stored in the database. The system resolves it to a GsCompanyId GSID and stores only the GSID. If name resolution fails (no match, multiple matches with MARKASERROR, or onNoMatch: ERROR), the record is rejected with error 0213.

Lookup Resolution System

Lookups let you pass human-readable values (names, email addresses) in the payload and have the API resolve them to Gainsight GSIDs before saving. Without lookups, all ID fields must be pre-resolved GSIDs.

Lookup Configuration Object

{
 "objectName": "GsUser",
 "fields": {
   "<payloadFieldName>": "<targetObjectFieldName>"
 },
 "lookupField": "Gsid",
 "multiMatchOption": "FIRSTMATCH",
 "onNoMatch": "ERROR"
}

Property	Type	Required	Description
objectName	String	Yes	Gainsight object to search. Common values: GsUser, Company, Company_Person, GsRelationship.
fields	Map	Yes	Maps a payload field name to a field on the target object. Multiple fields supported for compound lookups (example, email + company).
lookupField	String	Yes	The field to return from the matched record. Almost always Gsid.
multiMatchOption	String	No	Behavior when multiple records match. FIRSTMATCH = use the first result. MARKASERROR = reject the record. Default: FIRSTMATCH.
onNoMatch	String	No	Behavior when no record matches. ERROR = reject the record. SKIP = leave the field empty and continue. Default: ERROR.

Supported Lookup Objects

Object Name	Description	Typical Lookup Field
GsUser	Gainsight internal user	Email → Gsid
Company	Customer company	Name → Gsid
Company_Person	External contact / company person	Person_ID__gr.Email + Company_ID → Gsid
GsRelationship	Relationship record	Name → Gsid

Standard Lookup Keys

The following lookup key names are recognized by the system and drive specific field-level processing:

Lookup Key	Input Payload Field	Object	Purpose
AuthorId	Author (email)	GsUser	Resolves author email → User GSID
GsCompanyId	companyName	Company	Resolves company name → Company GSID
GsRelationshipId	relationship field	GsRelationship	Resolves relationship name → GSID
InternalAttendees	InternalAttendees (email list)	GsUser	Resolves attendee emails → User GSIDs
ExternalAttendees	ExternalAttendees (email list)	Company_Person	Resolves attendee emails → CompanyPerson GSIDs
FromUsers	fromUsers (email)	GsUser	Email From — internal users
ToUsers	toUsers (email)	GsUser	Email To — internal users
FromCompanyPersons	fromCompanyPersons (email)	Company_Person	Email From — external contacts
ToCompanyPersons	toCompanyPersons (email)	Company_Person	Email To — external contacts

Company_Person Lookup — Special Case

Company Person lookups require two payload fields: the person's email AND the resolved company GSID. The company ID scopes the search to the correct account, preventing ambiguous matches when the same email address appears under multiple companies.

"FromCompanyPersons": {
 "objectName": "Company_Person",
 "fields": {
   "fromCompanyPersons": "Person_ID__gr.Email",
   "GsCompanyId": "Company_ID"
 },
 "lookupField": "Gsid",
 "multiMatchOption": "FIRSTMATCH",
 "onNoMatch": "ERROR"
}

This configuration means: find a Company_Person where Person_ID__gr.Email equals the value of fromCompanyPersons in the payload and Company_ID equals the resolved GsCompanyId for that record.

The GsCompanyId lookup must also be configured for the same request — the Company Person lookup depends on it.

Email Fields — From, To

Email activity types support three recipient fields: From, To. Recipients can be internal Gainsight users or external Company Persons (contacts). There are two approaches:

Approach A: Using Direct GSIDs
Approach B: Using Email-Based Lookups

Approach A: Using Direct GSIDs

Pass Gainsight User or Company Person GSIDs directly. No lookup configuration is needed for these fields.

{
 "From": ["7a3f2b1c9d8e4f5a"],
 "To":   ["8b4c3d2e1f0a9b8c", "9c5d4e3f2a1b0c9d"],
}

From is always stored as a single value — if you pass a list, only the first element is used.
To accept arrays of GSIDs.
A record can contain a mix of GsUser GSIDs and Company_Person GSIDs in the same field.

Approach B: Using Email-Based Lookups

Pass email addresses and configure lookups to resolve them to GSIDs at processing time. Use this when you do not have pre-resolved GSIDs.

Payload fields for each email recipient role:

Payload Field	Lookup Key	Resolves Using	Stored As
fromUsers	FromUsers	GsUser.Email	User GSID → from_address
toUsers	ToUsers	GsUser.Email	User GSID list → to_recipients
fromCompanyPersons	FromCompanyPersons	Company_Person.Person_ID__gr.Email + company scope	CompanyPerson GSID → from_address
toCompanyPersons	ToCompanyPersons	Company_Person.Person_ID__gr.Email + company scope	CompanyPerson GSID list → to_recipients

You can mix internal users and external contacts within the same To field by providing both toUsers and toCompanyPersons with their respective lookups.

Attendees in the CC field of email must be passed to the To field of the request.

Attendees — Internal and External

Field Names

Type	API Field Name	Description
Internal	InternalAttendees	Gainsight users (employees) who attended the activity
External	ExternalAttendees	Company contacts (Company_Person records) who attended

Format

Both fields accept either format:

Comma-separated string: "alice.johnson@yourcompany.com,bob.smith@yourcompany.com"
JSON array: ["alice.johnson@yourcompany.com", "bob.smith@yourcompany.com"]

The API normalizes comma-separated strings into arrays before processing.

Lookup Configuration

Internal attendees (resolves emails → User GSIDs):

"InternalAttendees": {
"objectName": "GsUser",
 "fields": { "InternalAttendees": "Email" },
 "lookupField": "Gsid",
 "multiMatchOption": "FIRSTMATCH",
 "onNoMatch": "ERROR"
}

External attendees (resolves emails → Company_Person GSIDs):

"ExternalAttendees": {
 "objectName": "Company_Person",
 "fields": {
   "ExternalAttendees": "Person_ID__gr.Email",
   "GsCompanyId": "Company_ID"
 },
 "lookupField": "Gsid",
 "multiMatchOption": "FIRSTMATCH",
 "onNoMatch": "ERROR"
}

External attendee resolution requires a GsCompanyId lookup to also be configured — the company context is needed to scope the person search to the correct account.

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

Sample Request Body- Email Activity with From / To (Insert)

Log an email thread where a CSM followed up with the customer.


{
  "records": [
    {
      "ExternalId": "gmail-thread-20260414-8c4d3e2f",
      "Author": "alice.johnson@acme-cs.com",
      "ContextName": "Company",
      "TypeName": "Email",
      "Subject": "RE: AlphaCorp — Implementation Timeline",
      "Notes": "Hi Sarah,\n\nThanks for the update. We've aligned the engineering team on the April 28th go-live target. I'll share the technical specs by Thursday.\n\nBest,\nAlice",
      "ActivityDate": "2026-04-14T09:32:00.000+0000",
      "companyName": "AlphaCorp",
      "fromUsers": ["alice.johnson@acme-cs.com"],
      "toUsers": ["bob.smith@acme-cs.com"],
      "toCompanyPersons": ["sarah.lee@alphacorp.io"],
      "ExternalSource": "EXTAPI"
    }
  ],
  "lookups": {
    "AuthorId": {
      "objectName": "GsUser",
      "fields": { "Author": "Email" },
      "lookupField": "Gsid",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "GsCompanyId": {
      "objectName": "Company",
      "fields": { "companyName": "Name" },
      "lookupField": "Gsid",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "FromUsers": {
      "objectName": "GsUser",
      "fields": { "fromUsers": "Email" },
      "lookupField": "Gsid",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "ToUsers": {
      "objectName": "GsUser",
      "fields": { "toUsers": "Email" },
      "lookupField": "Gsid",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "ToCompanyPersons": {
      "objectName": "Company_Person",
      "fields": {
        "toCompanyPersons": "Person_ID__gr.Email",
        "GsCompanyId": "Company_ID"
      },
      "lookupField": "Gsid",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    }
         }
}

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 131,000 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. GSID value of Relationship Type object can be fetched from Data Management page.
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.
MilestoneType	String	-	If the ActivityTypeID or TypeName is set to Milestone, this field is mandatory in the Save Activity request.

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 131,000 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.
MilestoneType	String	-	If the ActivityTypeID or TypeName is set to Milestone, this field is mandatory in the Save Activity request.

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

Sample Request Body

{
    "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 131,000 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 131,000 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

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": [
        "Gsid",
        "CreatedDate",
        "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"
    },
    "orderBy": {
        "CreatedDate": "desc"
    },
    "limit": 5000,
    "offset": 0
}

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.