Skip to main content
Gainsight Inc.

Call To Action (CTA) API Documentation

  1. Last updated
  2. Save as PDF 
Gainsight NXT

 

The Call To Action (CTA) 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 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.

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 

API

Rate Limit

Asynchronous API Calls

10 calls per hour / 100 per day

Synchronous API Calls

100 API calls per min / 50,000 API call per day

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.

Notes:

  • Users can create/update only one CTA at a time.
  • External Reference ID is a mandatory pass for creating CTAs.
  • When constructing a request payload with a "linkedObjects" array, ensure that the "objectName" values are in lowercase if the source is MDA. For SFDC (Salesforce) source objects, the "objectName" should match the exact API name of the corresponding SFDC object.

Method

POST

Endpoint URL

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

    }
}

Notes: 

  • 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.
  • The proper way to use <br/> in the "Comments" field should be as follows:
    "Support risk since too many tickets <br/> are open Support risk since too many tickets are open<br/>Support risk since too many tickets are open."
    This will generate the desired output for the "Comments" field:
    Support risk since too many tickets 
    are open Support risk since too many tickets are open 
    Support risk since too many tickets are open

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

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

{
    "result": false,
    "errorCode": "COCKPIT_9703",
    "errorDesc": "Following lookup field have invalid filter configuration to resolve - User_Lookup__gc-> gsuser: UserLookup",
    "requestId": "8e35c24e-adf4-46fa-a0b5-48e26af1fbd7",
    "data": {},
    "message": null
}

Type not linked with linked object
Http status: 200

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "requestId": "02159926-4cba-4ed9-97a8-ec8c1c2d99f8",
    "data": {
        "success": [],
        "failure": [
            {
                "1": "COCKPIT_9702: Object(s) are not linked to the specific CTA type - customobjecttt1__gc"
            }
        ]
    },
    "message": null
}

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.

Notes:

  • External Reference ID is mandatory to pass for updating CTAs.
  • When constructing a request payload with a "linkedObjects" array, ensure that the "objectName" values are in lowercase if the source is MDA. For SFDC (Salesforce) source objects, the "objectName" should match the exact API name of the corresponding SFDC object.

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

PUT

Endpoint URL

/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

POST

Endpoint URL

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

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Please pass the expression for the respective conditions",
    "requestId": "91fbd3e5-0d41-412b-9e0b-858ec054004b",
    "data": {},
    "message": null
}

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

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Please pass the correct conditions",
    "requestId": "255a29ce-faa8-4a6f-b91a-6c446ade7037",
    "data": {},
    "message": null
}

  • Invalid input for page size or number:

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Invalid page size or, number",
    "requestId": "255a29ce-faa8-4a6f-b91a-6c446ade7037",
    "data": {},
    "message": null
}

  • Invalid fields in Select clause:

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Invalid fields in select clause - gsidasdf",
    "requestId": "255a29ce-faa8-4a6f-b91a-6c446ade7037",
    "data": {},
    "message": null
}

  • Invalid fields or operator passed in filters:

{
    "result": false,
    "errorCode": "COCKPIT_5101",
    "errorDesc": "Invalid fields or operator in where clause - MultiSelect__gc",
    "requestId": "e0b56748-1c81-4659-9734-4ada612971f2",
    "data": {},
    "message": null
}

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

{
  "fieldName": "DueDate",
  "value": ["2020-04-01","2020-04-30"],
  "alias": "A",
  "operator": "BTW"
}

  • Equal

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

  • Not Equal

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "NE"
}

  • Greater than

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "GT"
}

  • Greater than or Equal to

{
  "fieldName": "DueDate",
  "value": ["2020-04-14"],
  "alias": "A",
  "operator": "GTE"
}

  • 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

{
  "fieldName": "CustomDate__gc",
  "value": [],
  "alias": "A",
  "operator": "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

{
  "fieldName": "CompanyId__gr.Company_Test_Field__gc",
  "value": ["Manufacturing process has started"],
  "alias": "A",
  "operator": "NE"
}

  • 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

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

{
  "fieldName": "CompanyId__gr.csm__gr.gsid",
  "value": ["5HC5N0R2NDNAV"],
  "alias": "A",
  "operator": "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

GET

Endpoint URL

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
}

Error Codes

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

Error Code Error Message  Reason HTTP Status Code

COCKPIT_9705

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

Invalid format of Date/Date Time field

 400

COCKPIT_5101

 CTA Type details are not available

When CTA Type name or id is not provided

 400

COCKPIT_5101

 Provided type doesn't exist in the system

Invalid CTA Type in the system

 400

COCKPIT_5101

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

Invalid field in request

 400

COCKPIT_5103

 Associated records are invalid - %Field Names having issue%

Invalid IDs provided for associated records

 400

COCKPIT_6007

 Invalid GSID of CTA - %Field Names having issue%

Invalid GSID of CTA in request.

 400

COCKPIT_6007

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

Invalid value provided in Picklist/ Multi-picklist input

 400

COCKPIT_7501

 Invalid playbook name

Invalid playbook name provided in request

 400

COCKPIT_7501

 Invalid playbook ID

Invalid playbook id provided in request

 400

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

 400

COCKPIT_9703

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

Invalid object names provided in the lookup configuration

 400

COCKPIT_9703

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

Invalid lookup fields provided in the request.

 400

COCKPIT_9703

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

Invalid filter configuration in the lookup field

 400

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.

 400

COCKPIT_9700

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

Mandatory fields are not available for creating CTA action

 400

COCKPIT_9700

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

Mandatory fields are not available for updating CTA action

 400

COCKPIT_9707

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

Invalid standard picklist provided in the request

 400

 

  1. Back to top
  • Was this article helpful?

Recommended articles

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