Skip to main content
Gainsight Inc.

Task and Playbook API Documentation

  1. Last updated
  2. 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

  • pn - Page number (required = false) - (Default value - 1)

  • ps - Page Size (required = false) - (Default value - 1000)

  • includes - Include more fields to show in Select (required = false) - (Default Fields - Limited Set of mandatory fields to show)
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

  • et - entityType (required = false) 

  • entityId - entityType (required = false) 

  • active - provide active playbooks if true, all playbooks if no value passed (required = false)

  • type - type name where we can provide the type of playbooks to fetch
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.
  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
  2. Tags
    1. @APIs
    2. Cockpit APIs