Skip to main content
Gainsight Inc.

Call To Action (CTA) API Documentation

Gainsight NXT

This article supports Gainsight NXT, the next evolution of the Customer Success platform. If you are using Gainsight CS Salesforce Edition, you can find supporting documentation by visiting the home page, and selecting CS > Salesforce Edition.

Not sure what your team is using? Click here.

 

This document provides details of REST APIs that can be used to create and update CTAs, and also fetch CTAs details and get CTA configurations. 

Introduction 

Gainsight enables users to create and update CTAs, and also fetch CTA details and get CTA configurations using Cockpit Rest API’s. Not all teams who benefit from accessing CTA’s always use Gainsight. They have systems of their choice that they use a lot and will expect Gainsight to integrate better with them. Customers who have the development resources can use the APIs to build tighter and more customized integrations between Gainsight and other systems they use. These APIs give users the capability to integrate Cockpit data and build out these workflows in other systems. 

Business Use Cases: 

  • Finance team wants to create a CTA for the CSM if a customer has not made a payment from the system they use, for example, Salesforce/Zuora. 

  • When a user closes a case in Salesforce, they want to show the user a list of all the CTA’s which are associated with the case. And also, the user should select the CTA’s they want to close along with the case.

  • Export and Refresh Risk CTA Data in an Excel/Google sheet viewed by executives.

  • As an admin, I want to send notifications to CSMs about upcoming CTAs and CTAs user’s own using tools such as Workspaces. And we want to enable users to perform simple operations such as updating CTA status, posting comments, or closing a CTA.  

IMPORTANT: For rich text fields, the consumers of the API must ensure that the data they are sending is clean and does not contain any malicious tags.

Prerequisites 

To use these Cockpit APIs, ensure that you generate Access Token:

  • API Authentication: 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 will have to pass the access key as part of the request header “accesskey” for all of your API requests into Gainsight. The AccessKey does not expire.

Create CTA API

Create CTA API is used to create a new CTA in Gainsight. You can pass the mandatory fields like Company ID, CTA Type, CTA Name, and OwnerID inputs to create a CTA. Users must provide the Date fields in YYYY-MM-DD format. To populate Custom fields, users must append with ‘__gc’.

Users can also apply the playbook details and provide an object to associate with the created CTA. Use any identifier to resolve the corresponding company for Company ID and Owner ID.  Reference ID is used to return for the creation of which CTA the error has occurred. 

Users can provide additional fields on the CTA object to populate when creating the CTA. For CTA standard fields, the system uses default values based on the type, if values are not provided. Field Name must be provided as part of importing lookup configuration and it is case sensitive.

Note:

  • Users can create/update only one CTA at a time.

  • External Reference ID is a mandatory pass for creating CTAs.

Method Details

Request Method

POST

Request Params

NA

Request Endpoint

/v2/cockpit/cta/

Sample Request

{
    "requests": [
        {
            "record": {
                "referenceId": "1",
                "Name": "Too many Support Tickets open for customer",
                "SFDCID": "TZHYUJB8QBNHYUIIY",//Used to Resolve the CompanyID
                "OwnerEmail": "hsharma@gainsight.com", //Used to Resolve the OwnerID
                "DueDate": "2020-05-02",
                "type": "Risk",               //Pass Name of CTA Type
                "reason": "Support Risk",     //Pass Name of CTA Reason
                "status": "New",              //Pass Name of CTA Status
                "priority": "High",           //Pass Name of CTA Priority
                "playbook": "Support Risk Playbook", // Name of playbook to apply
                "Comments": "Support risk since too many tickets are open",
                "isEscalaed__gc": false,        // Custom Fields to populate
                "DT_Date__gc": "2020-04-28",
                "DT_DateTime__gc": "2020-04-17T22:30:00Z",
                "AdditionalNotes__gc": "Custom String field to populate",
                "DT_Email__gc": "test@test.com",
                "DT_MutliDDList__gc": "C; D",   // Multi-select values with names
                "DT_Percentage__gc": "15.67",
                "DT_String__gc": "Hey there",
                "Support_URL__gc": "https://www.google.com",
                "DT_RichTextArea__gc": "Hey there, How are you!!!"
            },
            "linkedObjects": [       //Linking an object while creating a CTA
                {
                    "id": "1Z021IVUBQ4OXQAILPJLBKGVQ2XS41KZ9L8S",
                    "store": "MDA",
                    "objectName": "support__gc" //Linked Object Name
                }
            ]
        }
    ],
    "lookups": {                  // To Resolve GSID Fields using any key
        "OwnerId": {              // Resolving CTA Owner via
            "fields": {
                "OwnerEmail": "Email"
            },
            "lookupField": "Gsid",
            "objectName": "gsuser",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        },
        "CompanyId": {         // Resolving Company using SFDCID
            "fields": {
                "SFDCID": "sfdcid"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }

    }
}

Note: API supports valid JSON. For readability, we have added comments to a few JSON keys about their functionality. While preparing a request, they must be removed.

Sample Success Response

{
  "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "0bf2f76c-01d6-42a2-b292-eb9166d77aa7",
    "data": {
        "success": [
            {
                "1": "1S01B8KR0ST6J5HC5NHIE7VNUDERF7E7QTC3"
            }
        ],
        "failure": []
  },
    "message": null
}

Sample Failure Responses

  • Sample failure response:

  • Request with invalid lookup object configuration
    Http status: 400

  • Request with invalid linked object configuration. Type not linked with linked object
    Http status: 200

Update CTA API

Update CTA API is used to update existing CTAs in Gainsight. CTA ID (GSID) and ReferenceID are two mandatory parameters for this API to identify which CTA to update and for the formatting of results. Users can provide the list of fields and their values  to update the CTA as per requirement. 

Users can also provide an object to associate with the CTA. For example, link a record to the existing CTA and not make any changes to the record.

Note: External Reference ID is mandatory to pass for updating CTAs.

Following are the available cascading options of Due Date:

  • ALL_OPEN_TASKS (Default)

  • PLAYBOOK_TASKS

  • NO

Following are the available cascading options of Owner:

  • OWNER (Default)

  • ALL_OPEN_TASKS

  • NO

Success or Failure of CTA update is sent in the response with a failure reason.

Method Details

Request Method

PUT

Request Params

NA

Request Endpoint

/v2/cockpit/cta/

Sample Request

{
  "requests": [
    {
      "record": {
        "referenceId": "1",                               //ID to return errors
        "Gsid": "1S01B8KR0ST6J5HC5N9LNPIQ4ID70SCNKM1T",  //CTA Id to identify the record to update
        "Name": "Onboarding CTA",                        //CTA Name
        "OwnerEmail": "hsharma@gainsight.com",
        "DueDate": "2020-05-05",
        "reason": "Bugs Risk",                           //Update CTA Reason
        "status": "New",                                 //Update CTA Status
        "priority": "High",                              //Update CTA Priority
        "PlaybookId__gr.Name": "Add Playbook",           //Apply or Append Playbook
        "Comments": "CTA Comments",                      //Replace the CTA Comments
        "dt_boolean__gc": true,                          //Update Custom Fields
        "DT_Currency__gc": 35.65,
        "DT_Date__gc": "2020-04-29",
        "DT_DateTime__gc": "2020-04-19T20:30:00Z",
        "DT_DDList__gc": "Kicked Off",
        "DT_GSID__gc": "1S01B8KR0ST6J5HC5N3OHVEVCVEFTGTLHIIX",
        "DT_MutliDDList__gc": "C; D",
        "DT_Percentage__gc": "18.93",
        "DT_String__gc": "Hello",
        "CompanyLookup": "Gainsight",
        "Name_Lookup1__gc": "Gainsight",
        "UserLookup": "Hitesh Sharma",
        "ownerCriteria": “ALL_OPEN_TASKS”,
        “dueDateCriteria”: “PLAYBOOK_TASKS”      },
      "linkedObjects": [                                  //Append Linked Object
        {
          "id": "1Z027IA57F6SFBKJUYU9B0BI41YYIRB8IIEH",
          "store": "MDA",                               //SFDC For SFDC Objects
          "objectName": "support__gc"
        }
      ]
    }
  ],
  "lookups": {
    "OwnerId": {                                       //Updates the CTA Owner
      "fields": {
        "OwnerEmail": "Email"
      },
      "lookupField": "Gsid",
      "objectName": "gsuser",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
    "Comp_Lookup__gc": {                              //Updating custom lookup fields
      "fields": {
        "CompanyLookup": "Name"
      },
      "lookupField": "Gsid",
      "objectName": "company",
      "multiMatchOption": "FIRSTMATCH",
      "onNoMatch": "ERROR"
    },
  }
}

Sample Success Response

{
  "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "93ce3633-383b-4e2d-a07a-15e74e2f6d0a",
    "data": {      
        "success": [
            {
                "5": "1S01B8KR0ST6J5HC5N9LNPIQ4ID70SCNKM1T"
            }
        ],
        "failure": []
    },    "message": null
}

Sample Failure Response Template

{
    "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 CTA API

Fetch CTA API is used to fetch CTAs in Gainsight. A maximum limit of 1000 CTAs can be fetched in a single request. If there are more, use page number/page size to get details of all the CTA’s.

By default, the following standard CTA fields are fetched using this API; CompanyID, RelationshipID (If relationshipCTA), DueDate, CTA's GSID, isImportant, OwnerId, Owner's Full Name, Email, Priority Id, Priority name, Reason Id, Reason Name, Status Id, Status Name, Type Id, Type Name, Entity type (Company or Relationship), Company Name, Relationship Type Id, and Relationship Type Name. 

Date fields are returned in YYYY-MM-DD format and time in GMT. Linked object data can also be requested by providing “linkedObject = True”. 

Users can also request additional fields. Custom fields must be appended with ‘__gc’ and lookup fields are appended with ‘__gr’.

Users can also use filter parameters. Filter parameters can be fields or linked object records. For more information on filters for Simple and Advanced fetch calls, refer to the Sample Filters for Fetch CTAs section.

Method Details

Request Method

POST

Request Params

NA

Request Endpoint

/v2/cockpit/cta/list

Sample Request

{
    "select": [          
        "name",
        "customDate__gc",             // Additional Custom Field
        "CompanyId__gr.Name",         // Get data from lookup fields
        "CompanyId__gr.Arr",
        "CompanyId__gr.Csm_gr.Email", // Second level lookup fields
        "Comments",
        "Days Due"
        "Quoted_ARR__gc",
        "custom_picklist__gc",
        "Renewal_Date__gc"
    ],
    "linkedObject": true,             //Fetch Linked Objects Data as well
    "where": {                        //Filter Conditions
        "conditions": [
        {
          "associatedRecord": true,   //Filter based on Linked Objects
          "value": [
              "5002v00002ikxl0AAA",
              "1Z02G2ZIY14G9VKJ2NW0N6VN0EQE780AR0HZ"
          ],
          "alias": "A",
          "operator": "INCLUDES"
        },
        {
          "fieldName": "DueDate",
          "value": [
              "2020-04-14"
            ],
            "alias": "B",
            "operator": "EQ"
            }
        ],
        "expression": "A AND B"
    },
    "pageSize": 100,
    "pageNumber": 1
}

Sample Success Response 

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "f742e83d-4af3-4285-bd20-48686a2b3e17",
    "data": [
        {
            "CompanyId": "1P02ZUWNMOPV5SZ6ZLG7TZJMDCB8QNDDCACX",
            "CompanyId__gr.Arr": 998765.00000000000,
            "CompanyId__gr.Company_Test_Field__gc": "Company test field",
            "CompanyId__gr.CreatedBy": "1P015825RVB81GPY5OJQ2I4OLHR6DNBOYVZU",
            "CompanyId__gr.CurrencyIsoCode": "USD",
            "CompanyId__gr.Name": "IBM",
            "DueDate": "2020-04-14T11:30:00Z",
            "EntityType": "COMPANY",
            "Gsid": "1S01B8KR0ST6J5HC5N9X9GVU1LXJCHOYG7IS",
            "IsClosed": false,
            "IsImportant": false,
            "Name": "Tomorrow",
            "OwnerId": "1P015825RVB81GPY5OTDQ4GYW31IZC14GWQR",
            "OwnerId__gr.FirstName": "Hitesh",
            "OwnerId__gr.LastName": "Sharma",
            "OwnerId__gr.User_Number__gc": 56738,
            "PriorityId": "1I0016MVH7ECQMT12KZPJI2HPSK7AC2E4VCR",
            "PriorityId__gr.IsActive": true,
            "PriorityId__gr.Name": "Medium",
            "ReasonId": "1I003F6D392Y2KJ97AYOAB5WH6C1RSE1XT0E",
            "ReasonId__gr.Name": "Other",
            "StatusId": "1I0017YS8AFRMU8633PP4GQ7M1OFAHSBMCK0",
            "StatusId__gr.Name": "New",
            "TypeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "TypeId__gr.Name": "Risk",
            "associatedRecords": [
                {
                    "recordId": "1Z02G2ZIY14G9VKJ2NW0N6VN0EQE780AR0HZ",
                    "objectName": "customobject__gc",
                    "source": "MDA"
                }
            ]
        },
        {
            "CompanyId": "1P02ZUWNMOPV5SZ6ZLG7TZJMDCB8QNDDCACX",
            "CompanyId__gr.Arr": 998765.00000000000,
            "CompanyId__gr.Company_Test_Field__gc": "Company test field for string filters to do the test",
            "CompanyId__gr.CreatedBy": "1P015825RVB81GPY5OJQ2I4OLHR6DNBOYVZU",
            "CompanyId__gr.CurrencyIsoCode": "USD",
            "CompanyId__gr.Name": "IBM",
            "CustomDateTime__gc": "2020-04-17T22:00:00Z",
            "CustomDate__gc": "2020-04-22",
            "Custom_picklist__gc": "1I0054U9FAKXZ0H26HCDNCOD7NQT456P7RJL",
            "DueDate": "2020-04-14T11:30:00Z",
            "EntityType": "COMPANY",
            "Gsid": "1S01B8KR0ST6J5HC5NFP4LHLPQK80RWOD1NJ",
            "IsClosed": false,
            "IsImportant": false,
            "Name": "Today",
            "Name_Lookup1__gc": "IBM",
            "Name_Lookup1__gr.ModifiedDate": "2020-04-14T09:21:25.612Z",
            "Name_Lookup1__gr.Name": "IBM",
            "OwnerId": "1P015825RVB81GPY5OTDQ4GYW31IZC14GWQR",
            "OwnerId__gr.FirstName": "Hitesh",
            "OwnerId__gr.LastName": "Sharma",
            "OwnerId__gr.User_Number__gc": 56738,
            "PriorityId": "1I0016MVH7ECQMT12KZPJI2HPSK7AC2E4VCR",
            "PriorityId__gr.IsActive": true,
            "PriorityId__gr.Name": "Medium",
            "ReasonId": "1I003F6D392Y2KJ97AYOAB5WH6C1RSE1XT0E",
            "ReasonId__gr.Name": "Other",
            "StatusId": "1I0017YS8AFRMU8633PP4GQ7M1OFAHSBMCK0",
            "StatusId__gr.Name": "New",
            "TypeId": "1I00650WACZ7F0X9HR1K21ZPDOQ71DFE4KFG",
            "TypeId__gr.Name": "Risk",
            "User_Lookup__gc": "1P015825RVB81GPY5OTDQ4GYW31IZC14GWQR",
            "User_Lookup__gr.ModifiedDate": "2020-04-14T09:22:03.178Z",
            "User_Lookup__gr.Name": "Hitesh Sharma",
            "associatedRecords": [
                {
                    "recordId": "5002v00002ikxl0AAA",
                    "objectName": "Case",
                    "source": "SFDC"
                },
                {
                    "recordId": "1Z02G2ZIY14G9VKJ2NW0N6VN0EQE780AR0HZ",
                    "objectName": "customobject__gc",
                    "source": "MDA"
                }
            ]
        }
    ],
    "message": null
}

Sample Failure Responses

  • When no fields are passed in Select clause:

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Please add fields in the select clause",
    "requestId": "cfb0da1e-90dd-42dc-88ff-2ff1d2671ce6",
    "data": {},
    "message": null
}
  • When the expression value is not passed:

  • When the expression is passed but the conditions are not available:

  • Invalid input for page size or number:

  • Invalid fields in Select clause:

  • Invalid fields or operator passed in filters:

Sample Filters to Fetch CTAs

All the filters mentioned below must be encoded and then provided in URL. Here, the mentioned filters are the decoded version.

Advanced Fetch Calls

Following are some of the examples of advanced fetch calls filters:

Date Filters

These are some of the operators supported in advanced Date filters fetch calls:

  • Between

  • Equal

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal

  • Greater than

  • Greater than or Equal to

  • Less than

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "LT"
}
  • Less than or Equal to

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "LTE"
}
  • Is Null

{
  "fieldName": "CustomDate__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

Special Cases in Date Filters

There are many special tokens available in date filters. Following are some of the special cases that can be used to fetch CTAs using date filters:

  • Today:

{
  "fieldName": "DueDate",
  "value": [],
  "alias": "A",
  "operator": "EQ",
  "literal": "TODAY"
}
  • Yesterday

{
  "fieldName": "DueDate",
  "value": [],
  "alias": "A",
  "operator": "EQ",
  "literal": "YESTERDAY"
}
  • Tomorrow

{
  "fieldName": "DueDate",
  "value": [],
  "alias": "A",
  "operator": "EQ",
  "literal": "TOMORROW"
}
  • Next N days

{
  "fieldName": "DueDate",
  "value": [30],
  "alias": "A",
  "operator": "EQ",
  "literal": "LAST_N_DAYS"
}
User Filters

It is a special type of filter only available when the lookup is on a GSUser object. These are some of the operators supported in advanced User filters fetch calls:

  • Equal

  • Not Equal

  • Starts With

  • Contains

  • Does not Contains

Special Cases in Date Filters

There are three special tokens available in user filters. These tokens can be used only with Equal and Not Equal operators.

  • Current User filter

{
  "fieldName": "OwnerId",
  "value": [],
  "alias": "A",
  "operator": "EQ",
  "literal": "CURRENT_USER"
}
  • All Users filter

{
  "fieldName": "OwnerId",
  "value": [],
  "alias": "A",
  "operator": "EQ",
  "literal": "ALL_USERS"
}
  • Other User filters

{
  "fieldName": "OwnerId",
  "value": ["1P015825RVB81GPY5OTDQ4GYW31IZC14GWQR"],
  "alias": "A",
  "operator": "NE",
  "literal": "OTHER_USER"
}
String Filters

These are some of the operators supported in advanced String filters fetch calls:

  • Equal

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": ["Manufacturing process has started"],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal

  • Starts with

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": ["Manufacturing"],
  "alias": "A",
  "operator": "STARTS_WITH"
}
  • Contains

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": ["process"],
  "alias": "A",
  "operator": "CONTAINS"
}
  • Does not contains

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": ["process"],
  "alias": "A",
  "operator": "DOES_NOT_CONTAINS"
}
  • Is Null

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Boolean Filters

These are some of the operators supported in advanced Boolean filters fetch calls:

  • Equal

{  "fieldName": "IsImportant",
  "value": [true],
  "alias": "A",
  "operator": "NE"
}
  • Not Equal

{
  "fieldName": "CompanyId__gr.CompanyBoolean__gc",  "value": [true],
  "alias": "A",
  "operator": "EQ"
}
Number Filters

These are some of the operators supported in advanced Number filters fetch calls:

  • Equal

{
  "fieldName": "ownerId__gr.user_number__gc",
  "value": [10],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal

{
  "fieldName": "age",
  "value": [10],
  "alias": "A",
  "operator": "NE"
}
  • Greater Than

{
  "fieldName": "companyId__gr.csm__gr.user_number__gc",
  "value": [10],
  "alias": "A",
  "operator": "GT"
}
  • Greater than or equal to

{
  "fieldName": "age",
  "value": [10],
  "alias": "A",
  "operator": "GTE"
}
  • Less than

{
  "fieldName": "age",
  "value": [10],
  "alias": "A",
  "operator": "LT"
}
  • Less than or equal to

{
  "fieldName": "age",
  "value": [10],
  "alias": "A",
  "operator": "LTE"
}
  • Is Null

{
  "fieldName": "companyId__gr.csm__gr.user_number__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "companyId__gr.csm__gr.user_number__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Percentage Filters

These are some of the operators supported in advanced Percentage filters fetch calls:

  • Equal

{
  "fieldName": "companyId__gr.company_percentage__gc",
  "value": [83],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal

{
  "fieldName": "companyId__gr.company_percentage__gc",
  "value": [83],
  "alias": "A",
  "operator": "NE"
}
  • Greater Than

{
  "fieldName": "companyId__gr.csm__gr.user_percentage__gc",
  "value": [10],
  "alias": "A",
  "operator": "GT"
}
  • Greater than or equal to

{
  "fieldName": "companyId__gr.csm__gr.user_percentage__gc",
  "value": [10],
  "alias": "A",
  "operator": "GTE"
}
  • Less than

{
  "fieldName": "ownerId__gr.user_percentage__gc",
  "value": [60],
  "alias": "A",
  "operator": "LT"
}
  • Less than or equal to

{
  "fieldName": "ownerId__gr.user_percentage__gc",
  "value": [30],
  "alias": "A",
  "operator": "LTE"
}
  • Is Null

  • Is Not Null

{
  "fieldName": "companyId__gr.csm__gr.user_percentage__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Currency Filters

These are some of the operators supported in advanced Currency filters fetch calls:

  • Equal

{
  "fieldName": "ownerId__gr.user_currency__gc",
  "value": [83],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal

{
  "fieldName": "companyId__gr.company_currency__gc",
  "value": [83],
  "alias": "A",
  "operator": "NE"
}
  • Greater Than

{
  "fieldName": "companyId__gr.csm__gr.user_currency__gc",
  "value": [10],
  "alias": "A",
  "operator": "GT"
}
  • Greater than or equal to

{
  "fieldName": "companyId__gr.csm__gr.user_currency__gc",
  "value": [10],
  "alias": "A",
  "operator": "GTE"
}
  • Less than

{
  "fieldName": "ownerId__gr.user_currency__gc",
  "value": [60],
  "alias": "A",
  "operator": "LT"
}
  • Less than or equal to

{ 
  "fieldName": "ownerId__gr.user_percentage__gc",
  "value": [30],
  "alias": "A",
  "operator": "LTE"
}
  • Is Null

{
  "fieldName": "companyId__gr.csm__gr.user_percentage__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "companyId__gr.csm__gr.user_percentage__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Picklist Filters

These are some of the operators supported in advanced Picklist filters fetch calls:

  • Equal 

{
  "fieldName": "companyId__gr.csm__gr.user_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HF3ESSG4UYB5YTTPQVV"],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal 

{
  "fieldName": "CompanyId__gr.company_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HF3ESSG4UYB5YTTPQVV"],
  "alias": "A",
  "operator": "NE"
}
  • Starts with

{
  "fieldName": "custom_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HCDNCOD7NQT456P7RJL"],
  "alias": "A",
  "operator": "STARTS_WITH"
}
  • Contains

{
  "fieldName": "ownerId__gr.user_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HF3ESSG4UYB5YTTPQVV"],
  "alias": "A",
  "operator": "CONTAINS"
}
  • Does not contains

{
  "fieldName": "custom_picklist__gc",
  "value": ["process"],
  "alias": "A",
  "operator": "DOES_NOT_CONTAINS"
}
  • Includes

{
  "fieldName": "ownerId__gr.user_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HF3ESSG4UYB5YTTPQVV","1I0054U9FAKXZ0H26HTD7Y3TC7VE7MCN6BD0"],
  "alias": "A",
  "operator": "INCLUDES"
}
  • Excludes

{
  "fieldName": "ownerId__gr.user_picklist__gc",
  "value": ["1I0054U9FAKXZ0H26HTD7Y3TC7VE7MCN6BD0","1I0054U9FAKXZ0H26HCDNCOD7NQT456P7RJL"],
  "alias": "A",
  "operator": "CONTAINS"
}
  • Is Null

{
  "fieldName": "companyId__gr.csm__gr.user_picklist__gc",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "companyId__gr.csm__gr.user_picklist__gc",
  "value": [],
  "alias": "A",
"operator": "IS_NOT_NULL"
}
Multi-Picklist Filters

These are some of the operators supported in advanced Multi-Picklist filters fetch calls:

  • Includes

{
  "fieldName": "ownerId__gr.user_multipicklist__gc",
  "value": ["1I0054U9FAKXZ0H26HF3ESSG4UYB5YTTPQVV","1I0054U9FAKXZ0H26HTD7Y3TC7VE7MCN6BD0"],
  "alias": "A",
  "operator": "INCLUDES"
}
  • Excludes

{
  "fieldName": "ownerId__gr.user_multipicklist__gc",
  "value": ["1I0054U9FAKXZ0H26HTD7Y3TC7VE7MCN6BD0","1I0054U9FAKXZ0H26HCDNCOD7NQT456P7RJL"],
  "alias": "A",
  "operator": "EXCLUDES"
}
GSID Filters

These are some of the operators supported in advanced GSID filters fetch calls:

  • Equal 

{
  "fieldName": "gsid",
  "value": ["1S01B8KR0ST6J5HC5N0R2NDNAVC5V9P4GABM"],
  "alias": "A",
  "operator": "EQ"
}
  • Not Equal 

{
  "fieldName": "CompanyId__gr.gsid",
  "value": ["1P02ZUWNMOPV5SZ6ZLG7TZJMDCB8QNDDCACX"],
  "alias": "A",
  "operator": "NE"
}
  • Starts with

{
  "fieldName": "CompanyId__gr.gsid",
  "value": ["1P02ZUWNMOPV5"],
  "alias": "A",
"operator": "STARTS_WITH"
}
  • Contains

  • Does not contains

{
  "fieldName": "ownerId",
  "value": ["VC5V9P4GABM"],
  "alias": "A",
  "operator": "DOES_NOT_CONTAINS"
}
  • Is Null

{
  "fieldName": "CompanyId__gr.csm__gr.gsid",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "companyId__gr.csm__gr.gsid",
  "value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Lookup Filters

These are some of the operators supported in advanced Lookup filters fetch calls:

  • Equal 

{
  "fieldName": "companyId",
  "value": ["1P02ZUWNMOPV5SZ6ZLG7TZJMDCB8QNDDCACX"],
  "alias": "A",
"operator": "EQ"
}
  • Not Equal 

{
  "fieldName": "companyId",
  "value": ["1P02ZUWNMOPV5SZ6ZLG7TZJMDCB8QNDDCACX"],
  "alias": "A",
  "operator": "NE"
}
  • Starts with

{
  "fieldName": "CompanyId",
  "value": ["1P02ZUWNMOP"],
  "alias": "A",
  "operator": "STARTS_WITH"
}
  • Contains

​​​​​​​{
  "fieldName": "ownerId",
  "value": ["PV5SZ6ZLG7TZJMD"],
  "alias": "A",
  "operator": "CONTAINS"
}
  • Does not contains

{
  "fieldName": "ownerId",
  "value": ["1S01B8KR0ST6J5HC5N0R2NDNAVC5V9P4GABM"],
  "alias": "A",
  "operator": "DOES_NOT_CONTAINS"
}
  • Is Null

{
  "fieldName": "companyId",
  "value": [],
  "alias": "A",
  "operator": "IS_NULL"
}
  • Is Not Null

{
  "fieldName": "companyId",
"value": [],
  "alias": "A",
  "operator": "IS_NOT_NULL"
}
Linked Object Filters

These are some of the operators supported in advanced Linked Object filters fetch calls:

  • Equals

{
  "value": ["1Z027IA57F6SFBKJUYMKE58DPGDEHC14BP2F"],
  "associatedRecord" : true,
  "alias": "A",
  "operator": "EQ"
}
  • Not Equals

{
  "value": ["1Z027IA57F6SFBKJUYMKE58DPGDEHC14BP2F"],
  "associatedRecord" : true,
  "alias": "A",
  "operator": "NE"
}
  • Includes

{
  "value": ["1Z027IA57F6SFBKJUYMKE58DPGDEHC14BP2F", "1Z027IA57F6SFBKJUYT86Y0KE4JV9FK2IOCR"],
  "associatedRecord" : true,
  "alias": "A",
  "operator": "INCLUDES"
}
  • Excludes

{
  "value": ["1Z027IA57F6SFBKJUYMKE58DPGDEHC14BP2F", "1Z027IA57F6SFBKJUYT86Y0KE4JV9FK2IOCR"],
  "associatedRecord" : true,
  "alias": "A",
  "operator": "EXCLUDES"
}

Get CTA Configuration (getCockpitConfig) API

Get CTA Configuration API is used to get the CTA Configuration for the CTA Type, Reason, Status, and Priority. Users can select what picklist values they want to return. For example, category=CTA_Status only returns the CTA Status. 

For the CTA Type data, the system returns all the dependent picklists. For example, when CTA type is returned, all the values of status, priority, and reason are returned.

‘et’ is used for the entity type for which the picklist configuration should be returned. ‘entityid’ is the entity id for relationships that is the relationship type ID.

Method Details

Request Method

GET

Request Params

et(required = false), entityId(required = false), category(required = true)

Request Endpoint

/v2/cockpit/admin/picklist/lite?category=CTA_STATUS,CTA_PRIORITY,CTA_TYPE&et=COMPANY

Sample Success Response

The following request is for CTA Reason:

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "1fb36683-fab0-4c2e-90cd-ab5feff015da",
  "data": {
    "CTA_REASON": [
      {
        "name": "Usage Drop",
        "gsid": "1I003F6D392Y2KJ97AOGZLY1OQHFA7AF1PGQ",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_REASON",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      },
      {
        "name": "New Customer Kickoff",
        "gsid": "1I003F6D392Y2KJ97AN2OW5I69WFNBPJTY6A",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_REASON",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      },
      {
        "name": "Onboarding",
        "gsid": "1I003F6D392Y2KJ97A2VH5Q8FGAI458OH3KT",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_REASON",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      },
      {
        "name": "Habits Risk",
        "gsid": "1I003F6D392Y2KJ97AFO9J9X36I4IU97KNH7",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_REASON",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      },
      {
        "name": "Bugs Risk",
        "gsid": "1I003F6D392Y2KJ97ANP5QXASLDHSPLT4W0D",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_REASON",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      }
    ]
  },
  "message": null
}

The following request is for CTA Status:

{
  "result": true,
  "errorCode": null,
  "errorDesc": null,
  "requestId": "eeb9e58b-0b64-444b-bb62-5da18b85c11a",
  "data": {
    "CTA_STATUS": [
      {
        "name": "Closed Invalid",
        "gsid": "1I0017YS8AFRMU8633C2ZBBD51H55X5JDOA6",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_STATUS",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      },
      {
        "name": "Closed Success",
        "gsid": "1I0017YS8AFRMU8633IA46KYK36YXW881F0W",
        "active": true,
        "entityType": "GLOBAL",
        "picklistCategory": "CTA_STATUS",
        "typeId": "1I00650WACZ7F0X9HRPORQFJY1E53HXG18T8",
        "typeName": "ALL_CTA_TYPE"
      }
    ]
  },
  "message": null
}

Failure Responses

The following table illustrates the different type of error messages and failure reason:

Error Message Failure Reason

COCKPIT_9705: Issue in date/date time field(s) - %Field Names having issue%

Invalid format of Date/DateTime field.

COCKPIT_5101: CTA Type details are not available

When CTA Type name or id is not provided.

COCKPIT_5101: Provided type doesn't exist in the system

Invalid CTA Type in the system.

COCKPIT_5101: Fields are not available in the object - %Field Names having issue%

Invalid field in request.

COCKPIT_5103: Associated records are invalid - %Field Names having issue%

Invalid IDs provided for associated records.

COCKPIT_6007: Invalid GSID of CTA - %Field Names having issue%

Invalid GSID of CTA in request.

COCKPIT_6007: Issue in Picklist/Multi-picklist input - %Field Names having issue%

Invalid value provided in Picklist/ Multi-picklist input.

COCKPIT_7501: Invalid playbook name

Invalid playbook name provided in request.

COCKPIT_7501: Invalid playbook ID

Invalid playbook id provided in request.

COCKPIT_9702: Objects are not linked to the specific CTA type - %Field Names having issue%

When objects mentioned in the request are not configured to the specific CTA type.

COCKPIT_9703: Following objects in lookup configuration are invalid - %Field Names having issue%

Invalid object names provided in the lookup configuration.

COCKPIT_9703: Invalid lookup field(s) found in the request - %Field Names having issue%

Invalid lookup fields provided in the request.

COCKPIT_9703: Following lookup field have invalid filter configuration to resolve - %Field Names having issue%

Invalid filter configuration in the lookup field.

COCKPIT_9704: Following lookup field should have at least one filter to resolve - %Field Names having issue%

When no filters are provided for the lookup field.

COCKPIT_9700: Missing mandatory fields for create - %Field Names having issue%

Mandatory fields are not available for creating CTA action.

COCKPIT_9700: Missing mandatory fields for update - %Field Names having issue%

Mandatory fields are not available for updating CTA action.

COCKPIT_9707: Invalid Picklist(s) - %Field Names having issue%

Invalid standard picklist provided in the request.

 

  • Was this article helpful?