Task and Playbook API Documentation
- Last updated
- Save as PDF
Gainsight NXT
The Task and Playbook APIs are organized around REST (Representational State Transfer). This article explains Admins the details of how these REST APIs can be used to create and update tasks, and also fetch tasks and playbooks details.
Introduction
Gainsight now enables users to create and update tasks, and also fetch tasks and playbooks details using Cockpit Rest API’s.
Business Use Case: Not all teams who benefit from accessing Cockpit Data always use Gainsight. They have systems of their choice that they use and expect Gainsight to integrate better with them. Customers with development resources can use APIs to build tighter and more customized integrations between Gainsight and other systems. These APIs give users the capability to integrate Cockpit data and build out workflows in other systems.
Users can perform the following actions using Cockpit Rest API’s:
- Create Task: This will create a new task for an existing CTA.
- Update Task: This will update the details for any existing task.
- Fetch Task: This will return the list of tasks that are associated with a CTA.
- Fetch Playbook: This will fetch the playbook configuration to apply for a CTA.
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 |
Create Task API
The Create Task API is used to create a new CSTask in Gainsight. You can pass the mandatory fields like Company ID/Relationship ID, CTA ID, Task Name, OwnerID inputs to create a Task.
For CompanyID & Owner ID, you can use any identifier to resolve to the corresponding company.
Note: Users can create/update only one Task at a time.
Users must provide the Date fields in YYYY-MM-DD format.
Users can pass additional fields they want to populate when creating the Task (fields on the CSTask object). ReferenceID is used to return for the creation of which Task has an error occurred. It can be any unique value for the set of CSTask.
It is up to the application calling the API to ensure that the correct values of Type, Status, Priority are passed. In case of a configuration mismatch, an error is displayed.
Note: The task created using this API is CStask, and not an EmailTask.
Method Details
API Details | Description |
---|---|
Request Method |
POST |
Request Params |
NA |
Request Endpoint |
/v2/cockpit/task |
Sample Request
{
"requests": [
{
"record": {
"referenceId": "123",
"CtaId": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
"Name": "Ext-T5",
"OwnerEmail": "athakur@gainsight.com",
"DueDate": "2020-05-09",
"status": "New",
"priority": "High",
"Description": "Hey!! How are you!!",
"DT_Boolean__gc": true,
"DT_Currency__gc": "43.68",
"DT_Date__gc": "2020-05-19",
"DT_DateTime__gc": "2020-06-16T12:30:00Z",
"DT_Picklist__gc": "New Customer",
"DT_Email__gc": "test123@test.com",
"DT_GSID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
"DT_MultiPicklist__gc": "A; B",
"DT_Number__gc": "30.40",
"DT_Percentage__gc": "97.56",
"DT_RTA1__gc": "HEY, Anything New in coding world!!",
"DT_WhoID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
"DT_String__gc": "Test",
"DT_URL__gc": "http://localhost:8091/v2/cockpit/task/",
"CompanyLookup": "IBM",
"DT_CompanyNameLookup__gc": "IBM",
"OwnerLookup": "athakur@gainsight.com"
}
}
],
"lookups": {
"OwnerId": {
"fields": {
"OwnerEmail": "Email"
},
"lookupField": "Gsid",
"objectName": "gsuser",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"DT_UserLookup__gc": {
"fields": {
"OwnerLookup": "Email"
},
"lookupField": "Gsid",
"objectName": "gsuser",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"DT_CompanyIDLookup__gc": {
"fields": {
"CompanyLookup": "Name"
},
"lookupField": "Gsid",
"objectName": "company",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
}
}
}
Sample Success Response
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "65eddbcf-3bbc-4c49-9f41-ea43536d2fe0",
"data": {
"success": [
{
"123": "1S032PUJRW05J6NDZ5QJ6SAGPRTLHPMPMLJ4"
}
],
"failure": []
},
"message": null
}
Sample Failure Response
- Sample failure response:
{
"result": false,
"errorCode": <ERROR_CODE>,
"errorDesc": <ERROR_DESC>, // If the issue comes while resolving the request
"requestId": <REQUEST_ID>,
"data": {
"success": [],
"failure": [
{
"1": "ERROR_MESSAGE" // Reference ID to highlight issue when creating
}
]
},
"message": null
}
- Request with invalid lookup object configuration (Http status: 400):
{
"result": false,
"errorCode": "COCKPIT_9703",
"errorDesc": "Following lookup field have invalid filter configuration to resolve - DT_UserLookup__gc -> gsuser: UserLookup",
"requestId": "8e35c24e-adf4-46fa-a0b5-48e26af1fbd7",
"data": {},
"message": null
}
Update Task API
The Update Task API is used to update an existing CSTask in Gainsight. You must mandatorily pass the CSTaskid (GSID) and ReferenceID for this API to identify which CSTask to update and for the formatting of results to create a Task.
Users can pass a list of fields and their values they want to update the CSTask. Success or Failure (with reason) of the update is sent in a response.
Following are the available cascading options of Due Date:
- ALL_OPEN_TASKS (Default)
- OPEN_TASKS_AND_CTA
- NO
Method Details
API Details | Description |
---|---|
Request Method |
PUT |
Request Params |
NA |
Request Endpoint |
/v2/cockpit/task |
Sample Request
{
"requests": [
{
"record": {
"referenceId": "ID1",
"gsid":"1S032PUJRW05J6NDZ5CIQGVI96XQP7SUCYGV",
"Name": "Covid-task1---update1",
"OwnerEmail": "mkandagatla@gainsight.com",
"DueDate": "2020-06-30",
"status": "Open",
"priority": "High",
"Description": "Hey!! How are you!!",
"DT_Boolean__gc": false,
"DT_Currency__gc": "45.68",
"DT_Date__gc": "2020-07-19",
"DT_DateTime__gc": "2020-07-16T12:30:00Z",
"DT_Picklist__gc": "New Customer",
"DT_Email__gc": "test12345@test.com",
"DT_GSID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
"DT_MultiPicklist__gc": "A; B",
"DT_Number__gc": "30.40",
"DT_Percentage__gc": "97.56",
"DT_RTA1__gc": "HEY, Anything New in coding world!!",
"DT_WhoID__gc": "1S01B8KR0ST6J5HC5NP2R0DDCNHN6QWEZ64A",
"DT_String__gc": "Test",
"DT_URL__gc": "http://localhost:8091/v2/cockpit/task/v2",
"CompanyLookup": "IBM",
"DT_CompanyNameLookup__gc": "IBM",
"OwnerLookup": "athakur@gainsight.com",
"dueDateCriteria":"OPEN_TASKS_AND_CTA"
}
}
],
"lookups": {
"OwnerId": {
"fields": {
"OwnerEmail": "Email"
},
"lookupField": "Gsid",
"objectName": "gsuser",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"DT_UserLookup__gc": {
"fields": {
"OwnerLookup": "Email"
},
"lookupField": "Gsid",
"objectName": "gsuser",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
},
"DT_CompanyIDLookup__gc": {
"fields": {
"CompanyLookup": "Name"
},
"lookupField": "Gsid",
"objectName": "company",
"multiMatchOption": "FIRSTMATCH",
"onNoMatch": "ERROR"
}
}
}
Sample Success Response
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "1e6cc9fa-2291-4fdc-99f1-af11f50b709b",
"data": {
"success": [
{
"ID1": "1S032PUJRW05J6NDZ5CIQGVI96XQP7SUCYGV"
}
],
"failure": []
},
"message": null
}
Sample Failure Response
{
"result": false,
"errorCode": <ERROR_CODE>,
"errorDesc": <ERROR_DESC>, // If the issue comes while resolving the request
"requestId": <REQUEST_ID>,
"data": {
"success": [],
"failure": [
{
"REFERENCE_ID": "ERROR_MESSAGE" // If the issue comes while processing the records
}
]
},
"message": null
}
Fetch Task List API
The Fetch Task List API is used to fetch the list of Tasks in Gainsight. A maximum of 1000 tasks can be fetched in a single request. If there are more, you can use page number/page size to get details of all the Tasks.
Method Details
API Details | Description |
---|---|
Request Method |
GET |
Request Params |
|
Path Params | GSID of CTA |
Request Body | None |
Request Endpoint | /v2/cockpit/task/list/<CTA_GSID> |
Sample Request URL: GET call without any query params | /v2/cockpit/task/list/<CTA_GSID> |
Sample Request URL: GET call with page number and size | /v2/cockpit/task/list/<CTA_GSID>?pn=1&ps=500 |
Sample Request URL: GET call with includes | /v2/cockpit/task/list/<CTA_GSID>?includes=DT_Date__gc,DT_DateTime__gc |
Sample Response
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "0eb5d905-9a0c-479e-b423-809eb0ded6bf",
"data": [
{
"ClosedDate": "2020-05-21",
"CtaId__gr.Name": "Ext. API 12.31",
"DueDate": "2020-05-20",
"Gsid": "1S032PUJRW05J6NDZ52CIIS4W30AE8L6G2TF",
"IsClosed": true,
"Name": "T2",
"OwnerId__gr.Name": "Ankush Thakur",
"PriorityId__gr.Name": "Medium",
"StatusId__gr.Name": "Closed Success",
"TypeId__gr.Name": "Task"
},
{
"CtaId__gr.Name": "Ext. API 12.31",
"DueDate": "2020-05-20",
"Gsid": "1S032PUJRW05J6NDZ5LXU7O2V74YIBZOJQ9Y",
"IsClosed": false,
"Name": "T1",
"OwnerId__gr.Name": "Ankush Thakur",
"PriorityId__gr.Name": "Medium",
"StatusId__gr.Name": "New",
"TypeId__gr.Name": "Task"
}
],
"message": null
}
Get Playbook Configuration (getPlaybookConfig) API
Get Playbook Configuration API is used to get the list of all the Playbook configurations ‘Et’ is used for the entity type for which the picklist configuration should be returned. ‘Etid’ is the entity id for relationships that is the relationship type ID.
Method Details
API Details | Description |
---|---|
Request Method |
GET |
Request Params |
|
Request Body | None |
Request Endpoint | /v2/cockpit/admin/playbook?active=true&et=COMPANY |
Sample Request URL with active, type specified | /v2/cockpit/admin/playbook?active=true&et=COMPANY&type=Risk,Expansion |
Sample Request without active, type specified | /v2/cockpit/admin/playbook?et=COMPANY |
Sample Response
{
"result": true,
"errorCode": null,
"errorDesc": null,
"requestId": "47c07857-3c5f-4be7-94c6-35425c349451",
"data": [
{
"name": "NPS® Promoter",
"gsid": "1I0012M2PCTA9UHOTWU9URUYK9YA3NMHKZAQ",
"active": true,
"entityType": "GLOBAL",
"typeId": "1I00650WACZ7F0X9HRGSO2D9AT5CEK0911SE",
"typeName": "Expansion"
},
{
"name": "Company All PB",
"gsid": "1I0012M2PCTA9UHOTWA0IOL2KWQE67QDVAK9",
"active": true,
"entityType": "COMPANY",
"typeId": "1I00650WACZ7F0X9HRJRX1GBJ9TG5ERJHGGY",
"typeName": "ALL_CTA_TYPE"
},
{
"name": "PB for Risk from Company",
"gsid": "1I0012M2PCTA9UHOTWVWQUD5FQD306ZCETTA",
"active": true,
"entityType": "COMPANY",
"typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
"typeName": "Risk"
},
{
"name": "Global All PB",
"gsid": "1I0012M2PCTA9UHOTW0GONZA5YY73UXZEDYD",
"active": true,
"entityType": "GLOBAL",
"typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
"typeName": "ALL_CTA_TYPE"
},
{
"name": "mkRiskCompanyPb",
"gsid": "1I0012M2PCTA9UHOTWETI540W8WP0IY4GKH0",
"active": true,
"entityType": "COMPANY",
"typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
"typeName": "Risk"
},
{
"name": "Covid Email Tasks",
"gsid": "1I0012M2PCTA9UHOTW0CQ6C8DGAZXF2ED5GH",
"active": true,
"entityType": "GLOBAL",
"typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
"typeName": "Risk"
},
{
"name": "Covid Tasks",
"gsid": "1I0012M2PCTA9UHOTWHMSXXRGOYN9QQXQG9N",
"active": true,
"entityType": "GLOBAL",
"typeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
"typeName": "Risk"
}
],
"message": null
}
NPS, Net Promoter, and Net Promoter Score are registered trademarks of Satmetrix Systems, Inc., Bain & Company and Fred Reichheld. |