Skip to main content
Gainsight Inc.

Customer Goals APIs

Gainsight NXT

 

This article explains how you can create, update, and fetch Customer Goals using APIs.

Introduction

The Customer Goals API helps you create, update and fetch Customer Goals. These are external APIs that help you integrate with other CRMs to bring data into Gainsight.

Authorization

The API access is controlled using a unique Access Key. You need to contact your Gainsight Admin to get an access key to the Gainsight tenant to which you want to send REST API requests. For more information on how to generate or share an access key, you can refer to the Generate API Access Key article.

Once you get your access key, you need 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 Customer Goals

The  Create Goal API lets you create new goals. You can either create a goal using the templates from the Goals Library or by passing mandatory fields which include Company, Relationship, Opportunity, Goal Name, and Status. You can also include values for other fields, as per your requirement.

Note: You can create only one Customer Goal at a time using this API. Bulk creation of customer goals is not supported.

Method

POST

Endpoint URL

/v1/csgoal/external/create

Sample Request Body


 {
    "requests": [
        {
           "record": {
               "Name": "create_test1",
               "StatusName" : "New",
               "DueDate": "2022-12-21",
               "Description": "<p><br>Desc 7</p>",
               "CompanyName": "IBM",
               "cf_picklist__gc": "CISCO",
               "EntityType": "COMPANY"
           },
           "association":
               {
                   "CTA": ["1S010R2NEBJLG2RT8IP6XWLYWZDDAVCXEK5J","1S010R2NEBJLG2RT8I19P44KW9MBT5QG6NBC"],
                   "SP": ["1S02J57N1K69N1VBJKLIBNH5YIJBBWEUOK4B"]
               }
       }
    ],
    "lookups": {
       "CompanyId": {
           "fields": {
               "CompanyName": "Name"
           },
           "lookupField": "Gsid",
           "objectName": "company",
           "multiMatchOption": "FIRSTMATCH",
           "onNoMatch": "ERROR"
       }
    }
}

Parameters

Parameter

(*mandatory)

Data Type

Description

Name*

String

A String value that contains the name of the goal.

StatusName*

String

A String value that contains the name of the status.

EntityType*

String

A String value that indicates if the goal is created on a Company, Relationship, or Opportunity.

CompanyName/

RelationshipName/

OpportunityName*
String A String value that contains the name of the Company, Relationship, or Opportunity.
Note: These fields need to be resolved using lookups, as demonstrated in the sample request.
TemplateId String A String value that contains the template data used for creating goals from the Goal’s Library.

DueDate

String

A String value that contains the due date of the goal in the format YYYY-MM-DD.

Description

String

A String value that contains the description of a goal.

RelationshipTypeId String A String value that indicates the relationship type of the goal. This is to be provided when the goal is created in a relationship.

Sample Success Response


{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "localizedErrorDesc": null,
   "requestId": "6ed304d6-f1bf-4bb1-8650-410c1819ef14",
   "data": {
       "goal": {
           "cf_picklist__gc": "CISCO",
           "CompanyId": "1P02GZA9BI8FRI07JF95E331G0FA4RHW6LUB",
           "CreatedById": "1P01413KLLPNNVG56OM8VLWE6CVV66QUHSES",
           "CreatedById__gr": {
               "Name": "Ankith Vaitla"
           },
           "CreatedDate": 1675156758024,
           "CurrencyIsoCode": "USD",
           "Description": "<p><br>Desc 7</p>",
           "DueDate": "2022-12-21",
           "EntityType": "COMPANY",
           "GoalCategory": "GOAL",
           "GoalTypeId": "1I002JOVZ5WU2870PLHILFPFXDHCUUGQKG6U",
           "Gsid": "1CG03GFNBH1NOBHOND0312RSO7BB9EGHHBX2",
           "ModifiedById": "1P01413KLLPNNVG56OM8VLWE6CVV66QUHSES",
           "ModifiedById__gr": {
               "Name": "Ankith Vaitla"
           },
           "ModifiedDate": 1675156758024,
           "Name": "CG3",
           "StatusId": "1I005IUOFEZ24SJ62ZZHOLW1BP2Z1M8O4IIN",
           "StatusId__gr": {
               "Name": "New"
           }
       },
       "userInfo": {
           "1P01413KLLPNNVG56OM8VLWE6CVV66QUHSES": {
               "gsid": "1P01413KLLPNNVG56OM8VLWE6CVV66QUHSES",
               "name": "Ankith Vaitla",
               "profilePicture": null
           }
       }
   },
   "message": null,
   "localizedMessage": null
}

Sample Failure Response


{
   "result": false,
   "errorCode": <>,
   "errorDesc": <>,
   "localizedErrorDesc": <>,
   "requestId": "b3551543-82ce-4e7c-81a6-1d2fa3852d15",
   "data": null,
   "message": "<error message> requestId",
   "localizedMessage": null,
   "errorInfo": null
}

Sample Failure Response for Invalid Status


{
   "timestamp": 1675399306376,
   "status": 500,
   "error": "Internal Server Error",
   "exception": "com.gainsight.cs.goal.exception.CSGoalException",
   "message": "Invalid StatusName provided in request",
   "path": "/csgoal/external/create"
}

Update Customer Goals 

The Update Goal API lets you update goal details such as associating or removing the association with CTAs and Success Plans.

Method

PUT

Endpoint URL

 /v1/csgoal/external/update

Sample Request Body


{
   "requests": [
       {
           "record": {
               "Name": "CG15",
               "StatusName" : "On Track",
               "DueDate": "2022-12-24",
               "Description": "<p><br>Updated Desc</p>",
               "Gsid": "1CG03GFNBH1NOBHOND412PHFQQEPGXWOQ1T9"
           },
           "dissociation":{
               "CTA": ["1S010R2NEBJLG2RT8IP6XWLYWZDDAVCXEK5J","1S010R2NEBJLG2RT8I19P44KW9MBT5QG6NBC"],
               "SP": ["1S02J57N1K69N1VBJKLIBNH5YIJBBWEUOK4B"]
           }
       }
   ]
}

Parameters

Parameter

(*mandatory)

Data Type

Description

Name

String

A String value that contains the name of the goal.

Note: This field cannot be left empty.

StatusName

String

A String value that contains the name of the status.

Note: This field need to be filled with relevant status.

DueDate

String

A String value that contains the due date of the goal in the format YYYY-MM-DD.

Description

String

A String value that contains the description of a goal.

GSID* String A String value that contains a Gsid of the goal.

Sample Success Response


{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "localizedErrorDesc": null,
   "requestId": "88f29db9-c88c-4678-9830-823f399aab56",
   "data": {
       "record": {
           "Description": "<p><br>Updated Desc</p>",
           "DueDate": "2022-12-24",
           "GoalCategory": "GOAL",
           "Gsid": "1CG03GFNBH1NOBHOND412PHFQQEPGXWOQ1T9",
           "ModifiedById": "1P01413KLLPNNVG56OM8VLWE6CVV66QUHSES",
           "ModifiedDate": 1675167677167,
           "Name": "CG15",
           "StatusId": "1I005IUOFEZ24SJ62ZBMHBO3HEB0OV9XW41D"
       },
       "updatedGoals": null,
       "properties": {}
   },
   "message": null,
   "localizedMessage": null
}

Sample Failure Response for Invalid GSID

{
   "timestamp": 1675399306376,
   "status": 500,
   "error": "Internal Server Error",
   "exception": "com.gainsight.cs.goal.exception.CSGoalException",
   "message": "Invalid StatusName provided in request",
   "path": "/csgoal/external/create"
}

Fetch Customer Goals 

The Fetch Goals API helps you retrieve goals along with their details. Filters can be applied based on company, relationship, status, opportunity, or any custom attribute.

Method

POST

Endpoint URL

 /v1/csgoal/external/fetch

Sample Request Body

{
   "select": [
       "CompanyId",
       "Name",
       "RelationshipId",
       "OpportunityId",
       "Gsid"
   ],
   "where": {
       "conditions": [
       {
         "fieldName": "Name",
         "value": ["CGnew"],
           "alias": "A",
           "operator": "EQ"
       }
       ],
       "expression": "A"
   },
   "pageSize": 100,
   "pageNumber": 1
}


Sample Success Response


{
   "result": true,
   "errorCode": null,
   "errorDesc": null,
   "localizedErrorDesc": null,
   "requestId": "88f29db9-c88c-4678-9830-823f399aab56",
   "data": {
       "recordList": [
           {
               "dataList": {
                   "CompanyId": "1P02GZA9BI8FRI07JF95E331G0FA4RHW6LUB",
                   "Description": "<p><br>Desc 7</p>",
                   "DueDate": "2023-02-01",
                   "Gsid": "1CG03GFNBH1NOBHONDL3T69ND47717CRSH0C",
                   "Name": "CGnew",
                   "StatusId": "1I005IUOFEZ24SJ62ZJYCFVNWXRC1SN73XSV"
               },
               "associatedCTAs": [],
               "associatedSPs": []
           }
       ]
   },
   "message": null,
   "localizedMessage": null
}

 Sample Failure Response for Invalid Field Queried

{
   "timestamp": 1675400090192,
   "status": 500,
   "error": "Internal Server Error",
   "exception": "com.gainsight.cs.goal.exception.CSGoalException",
   "message": "Invalid fields in select clause - Gsd",
   "path": "/csgoal/external/fetch"
}

External API

​​This API provides functionality to create, update, read, and delete goal templates. It supports external authentication to integrate seamlessly with external systems.

Template Create API

Method

CREATE

Endpoint URL

POST /v1/csgoal/external/template

Sample Request Body

{
    "requests": [
        {
            "record": {
                "Name": "Goal Template 1",                                 // Name of the goal template
                "GoalTypeName": "Default",                                 // Goal Type Name
                "StatusName": "Achieved",                                  // Status Name
                "DueDate": 2301,                                           // Number Of days
                "Description": "Description of goal template",          
                "CompName": "Meta",                                        // Value for Custom lookup field: comp_lookup_gsid__gc
                "cust_string_value__gc": "Facebook",                       // Value for custom string field
                "AssociatedWork":[
                    "1I005G22HP9QX1NRFCMFSKO6E6SA4ZP9ZQ4B"                 // GSID of associated work linked to above goal type
                    ],
                "metricsAssociation": [
                    {
                        "metricId": "1I0056K976K5AXWOB1HPW54VIC18AHVJ1TTG" // GSID of metric linked to above goal type
                    }
                ]
            }
        }
    ],
    "lookups": {                                                           // Lookup configuration for loookup fields added
        "comp_lookup_gsid__gc": {
            "fields": {
                "CompName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }
    }
}

Sample Success Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "3d11e7ad-70b0-4c3e-ab3f-14c420eb6cd3",
    "data": {
        "successList": [
            {
                "Name": "Goal Template 1",
                "DueDate": 2301,
                "Description": "Description of goal template",
                "cust_string_value__gc": "Facebook",
                "AssociatedWork": [
                    "1I005G22HP9QX1NRFCMFSKO6E6SA4ZP9ZQ4B"
                ],
                "comp_lookup_gsid__gc": "1P029JPET0U4HYGEAU5VBVM5IZ9G6MFOG1OT",
                "GoalTypeId": "1I00GO4Q83RGDEM94YP38XP5FK86FSQK45QL",
                "StatusId": "1I00GO4Q83RGDEM94YLQI7GFRATQYTVH8WNY",
                "Gsid": "1CG0GG9WM1TYAFSKZSMV3RW0VHC0FYIC4GE2"
            }
        ],
        "failureList": []
    },
    "message": null,
    "localizedMessage": null
}

Template Update API

Method

POST

Endpoint URL

Put /v1/csgoal/external/template

Sample Request Body

{
    "requests": [
        {
            "record": {
                "Gsid": "1CG01SX5TCMHZ0OXX0XMV01B68HZR4B6W7AX",     // Name of existing goal template
                "Name": "Goal Template Name - updated",             // Updated Name
                "DueDate": 25,                                      // Updated due days
                "StatusId": "1I005IUOFEZ24SJ62Z3MB2HWTSSQNX9MCSTB", // Updated Status
                "Description": "Updated All fields",                // UPdated description
                "CompNameGsid": "NEW",                              // Custom lookup field value
                "cust_string_value__gc": "custom value - updated",  // Custom string field value
                "AssociatedWork":[
                    "1I005G22HP9QX1NRFC58NVMRDRVLJE52KR1J",         // GSID of associated work linked to goal type
                    "1I005G22HP9QX1NRFC1AC0T2UHHYDO6ABJWO"         
                ],
                "metricsAssociation": [
                    {
                        "metricId": "1I0056K976K5AXWOB1KBHCAG860QZ6E3JG52"     // Metric GSID to be associated
                    }
                ],
                "metricsDissociation": [
                    {
                        "metricId": "1I0056K976K5AXWOB1P7YWFJNZOIUXW8YMEQ"      // Metric GSID to be dissociated
                    }
                ]
            }
        }
    ],
    "lookups": {
        "comp_lookup_gsid__gc": {
            "fields": {
                "CompNameGsid": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }
    }
}

Sample Success Response

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "8a7bc52d-981b-46ee-b687-57bc0f8cbc3d",
    "data": {
        "successList": [
            {
                "Gsid": "1CG01SX5TCMHZ0OXX0XMV01B68HZR4B6W7AX",
                "Name": "Goal Template Name - updated",
                "DueDate": 25,
                "StatusId": "1I005IUOFEZ24SJ62Z3MB2HWTSSQNX9MCSTB",
                "Description": "Updated All fields",
                "cust_string_value__gc": "custom value - updated",
                "AssociatedWork": [
                    "1I005G22HP9QX1NRFC58NVMRDRVLJE52KR1J",
                    "1I005G22HP9QX1NRFC1AC0T2UHHYDO6ABJWO"
                ],
                "comp_lookup_gsid__gc": "1P0275DAZIB1U41FWU0FBY7UJL61TUQZY6UV",
                "ModifiedById": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "ModifiedDate": 1738572131037
            }
        ],
        "failureList": []
    },
    "message": null,
    "localizedMessage": null
}

Template Delete API

Method

Delete

Endpoint URL

/v1/csgoal/external/template/delete

Sample Request Body

{
  "recordIds": ["1CG01SX5TCMHZ0OXX0750YQUGDZ3WPZ50KBY"]       // GSID of Goal Template to be deleted
}
Sample Response Body
{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "7e233017-27a5-43e2-9849-fd9a21c7e1e8",
    "data": {
        "failureList": [],
        "successList": [
            {
                "Deleted": true,
                "GoalCategory": "TEMPLATE",
                "Gsid": "1CG01SX5TCMHZ0OXX0Y3TG6GRSDAT31HGA3W",
                "ModifiedById": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "ModifiedDate": 1738576273062
            }
        ],
        "success": true,
        "failCount": 0
    },
    "message": null,
    "localizedMessage": null
}

Template Fetch API

Method

POST

Endpoint URL

/v1/csgoal/external/template/fetch

Sample Request Body

{
    "select": [                     // Fields whose data needs to be fetched
        "Name",
        "Gsid",
        "StatusId",
        "cust_string_value__gc",
        "CurrencyIsoCode"
    ],
    "where": {
    "conditions": [
      {
        "fieldName": "Name",
        "value": ["barca"],
        "alias": "A",
        "operator": "STARTS_WITH"
      },
      {
        "fieldName": "Name",
        "value": ["b"],
        "alias": "B",
        "operator": "CONTAINS"
      }
    ],
    "expression": "A AND B"
  },
    "pageSize": 10,
    "pageNumber": 1
}

Sample Success Body

{
    "recordList": [
        {
            "CreatedDate": 1738244376863,
            "CurrencyIsoCode": "USD",
            "DueDate": 0,
            "GoalTypeId": "1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
            "Gsid": "1CG01SX5TCMHZ0OXX0IXL1HYTPDCJ26XEY8N",
            "Name": "barca_template",
            "StatusId": "1I005IUOFEZ24SJ62ZSP4PI1BZX88VUL4V1Z",
            "cust_string_value__gc": "hello"
        }
    ]
}

Metric API

This API enables the creation, updating, and deletion of metrics within the system. It supports operations such as creating a new metric, associating it with goal types, updating existing metrics and associated goal types, and deleting metrics when necessary.

Metric Create API

Method

POST

Endpoint URL

POST /csgoal/external/metric/

Sample Request Body

{
    "requests": [
        {
            "record": {
                "name": "Metric Name 1",                        // Metric name
                "unitOfMeasure": "DECIMAL",                     // Unit of measure: DECIMAL/PERCENTAGE/CURRENCY
                "description": "<p>description</p>"
            },
            "associateGoalTypes": [
                "1I00GO4Q83RGDEM94YM7VTGXMVT1E1JLKNQB"          // GSID of goal type
            ],
            "associateGoalTypeNames": [
                "CP Goal Type"                                  // Goal Type Name
            ]
        }
    ]
}

Sample Success Body

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "b0f5d246-256b-4ce1-a20a-fc8acbc14039",
    "data": {
        "successList": [
            {
                "createdAt": 1738570023841,
                "deleted": false,
                "modifiedAt": 1738570023841,
                "createdBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "modifiedBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "name": "Metric Name 1",
                "description": "<p>description</p>",
                "unitOfMeasure": "DECIMAL",
                "displayOrder": 2658,
                "externalId": null,
                "active": true,
                "systemDefined": false,
                "gsid": "1I0056K976K5AXWOB1PGJTG9R7V2KYR0KBHZ"
            }
        ],
        "failureList": []
    },
    "message": null,
    "localizedMessage": null
}

Metric Update API

Method

PUT

Endpoint URL

PUT /csgoal/external/metric/

Sample Request Body

{
    "requests": [
        {
            "record": {
                "gsid": "1I0056K976K5AXWOB1PGJTG9R7V2KYR0KBHZ",    //  GSID of existing metric
                "name": "Metric Name 1 - updated",
                "unitOfMeasure": "PERCENTAGE",
                "description": "Updated description"
            },
            "associateGoalTypes": [
                "1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII"             // GSIDs of Goal Types to be associated with
            ],
            "associateGoalTypeNames": [
                "CG4"                                              // Names of Goal Types to be associated with
            ],
            "dissociateGoalTypes": [
                "1I00GO4Q83RGDEM94Y93I859J3I3KEZXZZF2"             // GSIDs of Goal TYpes to be dissociated with
            ],
            "dissociateGoalTypeNames": [
                "CG1"                                              // Names of Goal Types to be dissociated with
            ]
        }
    ]
}

Sample Success Body

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "6176221e-f7a8-47b9-acc8-944f7325e9f7",
    "data": {
        "successList": [
            {
                "createdAt": 1738570666302,
                "deleted": false,
                "modifiedAt": 1738570666302,
                "createdBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "modifiedBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "name": "Metric Name 1 - updated",
                "description": "Updated description",
                "unitOfMeasure": "PERCENTAGE",
                "displayOrder": 2659,
                "externalId": null,
                "active": true,
                "systemDefined": false,
                "gsid": "1I0056K976K5AXWOB1PGJTG9R7V2KYR0KBHZ"
            }
        ],
        "failureList": []
    },
    "message": null,
    "localizedMessage": null
}

Metric Error Response

   {
    "result": false,
    "errorCode": "VC_1002",
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "8813d263-71ff-44a3-8768-bb3e275eb9a5",
    "data": null,
    "message": "Unexpected error processing update metric: {}",
    "localizedMessage": null,
    "errorInfo": null
}

Metric Delete API

Method

DELETE

Endpoint URL

DELETE /csgoal/external/metrics

Sample Request Body

 {
  "recordIds": ["1I0056K976K5AXWOB1NB0L2GCSS77AMROJ8W"]          // GSID of the metric to be deleted

Sample Success Body

 {
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "60f673bc-da66-4ab6-8cfc-3c4eba8921e3",
    "data": {
        "deletedMetrics": [
            {
                "createdAt": 1738570738571,
                "deleted": true,
                "modifiedAt": 1738570738571,
                "createdBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "modifiedBy": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "name": "Copy of hi fjnjnrnds",
                "description": "<p>hi frns</p>",
                "unitOfMeasure": "PERCENTAGE",
                "displayOrder": 16,
                "externalId": null,
                "active": true,
                "systemDefined": false,
                "gsid": "1I0056K976K5AXWOB1NB0L2GCSS77AMROJ8W"
            }
        ]
    },
    "message": null,
    "localizedMessage": null
}

Error Response Body

 {
    "result": false,
    "errorCode": "VC_8026",
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "a797130b-5b97-46eb-9c24-7e1062bc5c65",
    "data": null,
    "message": "Metric is used in some goals or templates. Cannot delete the metric.",
    "localizedMessage": null,
    "errorInfo": {
        "usageInLayouts": [
            "Type1 rel goal type",
            "CP Goal Type",
        ],
        "usageInGoals": [
            {
                "gsid": "1CG0LXVS2HO4Y5ZF1FQZ4XVPN0VE1AJSZ415",
                "name": "gggg"
            }
        ],
        "hasUsage": true
    }
}

Goal API 

This API provides functionality to create, update, read, and delete goal templates. It supports external authentication to integrate seamlessly with external systems.

Goal Create API

Method

POST

Endpoint URL

POST /v1/csgoal/external/create

Sample Request Body

 {
    "requests": [
        {
            "record": {
                "Name": "Custom Goal 1",                                      // Pass Name of the goal
                "GoalTypeId": "1I00GO4Q83RGDEM94YM7VTGXMVT1E1JLKNQB",         // Pass Goal Type ID
                "StatusId": "1I005IUOFEZ24SJ62ZSP4PI1BZX88VUL4V1Z",           // Status ID
                "DueDate": "2025-01-07",
                "Description": "Feb Test Description ",
                "CompanyName": "IBM",                                 // Company for which the goal is to be created
                "CompName": "NEW",                                    // custom filed lookup on company:Gsid
                "cust_string_value__gc": "custom value",              // custom field value
                //"TemplateId": "1CG01SX5TCMHZ0OXX0PXTGFW1BHBFKJT7WCU",       // Pass templateID for Goal using template
                "metricsAssociation": [
                    {
                        "metricId": "1I0056K976K5AXWOB1XICUZ6DNSP6MZDCWNQ", // Pass GSID of metric linked with Goal Type
                        "baseValue": 10.0,
                        "actualValue": [
                            {
                                "value": 5.0,
                                "timestamp": "2025-01-04"
                            }
                        ],
                        "targetValue": 8.0
                    }
                ],
                "EntityType": "GLOBAL",
                "AssociatedWork": [
                    "1I005G22HP9QX1NRFCZYV81Y6QHH30TMXP49",         // GSIDs of associated work
                    "1I005G22HP9QX1NRFC4O3YXDHJ7BZDIAOE4M"]        
           
            },
            "association": {
                    "CTA": [
                        "1S015065Y1L4AP5SUXPXKGDH9S0CAT75F3CY", // GSIDs of CTAs
                        "1S015065Y1L4AP5SUXAN0N0MYVAFR66HRNQR" 
                    ],
                    "SP": [
                        "1S02JJSBDT2ZT78W7NMT0VBJP3QF725QD8RC", // GSIDs of SPs
                        "1S02JJSBDT2ZT78W7N3SX0J712OA8HOTBSQ7"
                    ]
                }
        }
    ],

    "lookups": {                                  // Lookup configurations of all the lookup fields
        "CompanyId": {
            "fields": {
                "CompanyName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        },
          "comp_lookup_gsid__gc": {
            "fields": {
                "CompName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }
    }
}

Sample Response Body

 {
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "8036a249-8c79-4bd7-9e5f-55721b276011",
    "data": {
        "goal": {
            "comp_lookup_gsid__gc": "1P0275DAZIB1U41FWU0FBY7UJL61TUQZY6UV",
            "CompanyId": "1P0275DAZIB1U41FWUD895S0FG38OCPH697T",
            "CreatedById": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
            "CreatedById__gr": {
                "Name": "Ujjwal Mahato"
            },
            "CreatedDate": 1738572893155,
            "CurrencyIsoCode": "USD",
            "cust_string_value__gc": "custom value",
            "Description": "Feb Test Description ",
            "DueDate": "2025-01-07",
            "EntityType": "GLOBAL",
            "GoalCategory": "GOAL",
            "GoalTypeId": "1I00GO4Q83RGDEM94YM7VTGXMVT1E1JLKNQB",
            "Gsid": "1CG0LXVS2HO4Y5ZF1FQY0E46C0NQWLLWPFX7",
            "MetricValues": [
                {
                    "metricId": "1I0056K976K5AXWOB1XICUZ6DNSP6MZDCWNQ",
                    "goalId": "1CG0LXVS2HO4Y5ZF1FQY0E46C0NQWLLWPFX7",
                    "baseValue": 10.0,
                    "actualValue": [
                        {
                            "gsid": null,
                            "value": 5.0,
                            "timestamp": "2025-01-04"
                        }
                    ],
                    "targetValue": 8.0,
                    "gsid": "1I0044QAWFWL9VNNWEEFLCSIUTFZ48SJAZEY"
                }
            ],
            "ModifiedById": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
            "ModifiedById__gr": {
                "Name": "Ujjwal Mahato"
            },
            "ModifiedDate": 1738572893155,
            "Name": "Custom Goal 1",
            "StatusId": "1I005IUOFEZ24SJ62ZSP4PI1BZX88VUL4V1Z",
            "StatusId__gr": {
                "Name": "Achieved"
            }
        },
        "userInfo": {
            "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT": {
                "gsid": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                "name": "Ujjwal Mahato",
                "profilePicture": null
            }
        }
    },
    "message": null,
    "localizedMessage": null
}

Goal Update Goal

Method

PUT

Endpoint URL

PUT /v1/csgoal/external/update

Sample Request Body

{
    "requests": [
        {
            "record": {
                "Gsid": "1CG0LXVS2HO4Y5ZF1F6TV4R7ZV0ZO6MPG6S1",      // GSID of existing Goal
                "Name": "Goal Template Name: Updated",               // Updated name
                "StatusId": "1I005IUOFEZ24SJ62ZSUKB6C3WN620DSIBYT", 
                "DueDate": "2025-01-31",
                "Description": " Feb : Update 1",
                "CompName": "NEW",
                "cust_string_value__gc": " Feb ujjwal  custom value - updated",
                "metricsAssociation": [                                       // GSIDs of metrics to be associated
                    {
                        "metricId": "1I0056K976K5AXWOB1KBHCAG860QZ6E3JG52",
                        "baseValue": 10.0,
                        "actualValue": [
                            {
                                "value": 8.0,
                                "timestamp": "2025-01-10"
                            }
                        ],
                        "targetValue": 8.0
                    }
                ],
                "metricsDissociation": [                                  // GSIDs of metrics to be dissociated
                    "1I0056K976K5AXWOB1KBHCAG860QZ6E3JG52",
                    "1I0056K976K5AXWOB1P7YWFJNZOIUXW8YMEQ" 
                ]
            },
          "association": {                                 // GSIDs of CTAs and SPs to be associated
            "CTA": [
                "1S015065Y1L4AP5SUXV96R83SMQ523UNWRXP"
            ],
            "SP": [
                "1S02JJSBDT2ZT78W7N3V2OYXMWCH2B720L51"
            ]
          },
        "dissociation": {                               // GSIDs of CTAs and SPs to be associated
            "CTA": [
                "1S015065Y1L4AP5SUXO3AX169IGVLKKJ5N7R"
            ],
            "SP": [
                "1S02JJSBDT2ZT78W7N326U5W640ZRK54GLAT"
            ]
        }
        }
    ],
    "lookups": {
        "comp_lookup_gsid__gc": {
            "fields": {
                "CompName": "Name"
            },
            "lookupField": "Gsid",
            "objectName": "company",
            "multiMatchOption": "FIRSTMATCH",
            "onNoMatch": "ERROR"
        }
    }
}

Sample Response Body

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "174f41bd-a5ef-4a95-a500-eb1bc383be0d",
    "data": {
        "record": {
            "comp_lookup_gsid__gc": "1P0275DAZIB1U41FWU0FBY7UJL61TUQZY6UV",
            "cust_string_value__gc": " Feb ujjwal  custom value - updated",
            "Description": " Feb : Update 1",
            "DueDate": "2025-01-31",
            "GoalCategory": "GOAL",
            "Gsid": "1CG0LXVS2HO4Y5ZF1F6TV4R7ZV0ZO6MPG6S1",
            "ModifiedById": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
            "ModifiedDate": 1738573668994,
            "Name": "Goal Template Name: Updated",
            "StatusId": "1I005IUOFEZ24SJ62ZSUKB6C3WN620DSIBYT"
        },
        "updatedGoals": null,
        "properties": {}
    },
    "message": null,
    "localizedMessage": null
}

Goal Fetch API

Method

POST

Endpoint URL

POST /v1/csgoal/external/fetch

Sample Request Body

{
    "select": [
        "Name",
        "Gsid",
        "StatusId",
        "cust_string_value__gc",
        "CurrencyIsoCode"
    ],
    "where": {
    "conditions": [
      {
        "fieldName": "Name",
        "value": ["barca"],
        "alias": "A",
        "operator": "STARTS_WITH"
      },
      {
        "fieldName": "Name",
        "value": ["b"],
        "alias": "B",
        "operator": "CONTAINS"
      }
    ],
    "expression": "A AND B"
  },
    "pageSize": 10,
    "pageNumber": 1
}

Sample Response Body

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "be36383b-41aa-414b-b078-b4842b926319",
    "data": {
        "recordList": [
            {
                "dataList": {
                    "CurrencyIsoCode": "USD",
                    "DueDate": "2025-01-30",
                    "GoalTypeId": "1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
                    "Gsid": "1CG0LXVS2HO4Y5ZF1F6YYCF1TN6O5RCW2ZTO",
                    "Name": "barca_template",
                    "StatusId": "1I005IUOFEZ24SJ62ZSP4PI1BZX88VUL4V1Z",
                    "cust_string_value__gc": "hello"
                },
                "associatedCTAs": [],
                "associatedSPs": [
                    {
                        "gsid": "1S02JJSBDT2ZT78W7NL2NR8BXMXALV76JBSC",
                        "name": "barca_sp 1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
                        "entityType": "COMPANY",
                        "ownerId": "1P01J0CQPQSRP90S3XLLTAL1EG7F0GQ6SFGX",
                        "statusId": "1I004Y368TQW84KNMBVMAMEBL1IOFF9APWGI",
                        "dueDate": "2025-01-31 11:30:00",
                        "closedCtaCount": null
                    }
                ]
            },
            {
                "dataList": {
                    "CurrencyIsoCode": "USD",
                    "GoalTypeId": "1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
                    "Gsid": "1CG0LXVS2HO4Y5ZF1FJINHVV1BOPDPEGV3J4",
                    "Name": "Barca custom goal ",
                    "StatusId": "1I005IUOFEZ24SJ62ZSUKB6C3WN620DSIBYT",
                    "cust_string_value__gc": "hello"
                },
                "associatedCTAs": [],
                "associatedSPs": [
                    {
                        "gsid": "1S02JJSBDT2ZT78W7NL2NR8BXMXALV76JBSC",
                        "name": "barca_sp 1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
                        "entityType": "COMPANY",
                        "ownerId": "1P01J0CQPQSRP90S3XLLTAL1EG7F0GQ6SFGX",
                        "statusId": "1I004Y368TQW84KNMBVMAMEBL1IOFF9APWGI",
                        "dueDate": "2025-01-31 11:30:00",
                        "closedCtaCount": null
                    }
                ]
            },
            {
                "dataList": {
                    "CurrencyIsoCode": "USD",
                    "DueDate": "2025-01-30",
                    "GoalTypeId": "1I00GO4Q83RGDEM94YUKVBH3OA6UU7RGBRII",
                    "Gsid": "1CG0LXVS2HO4Y5ZF1FLUUZU35FSKQ35Y65OE",
                    "Name": "barca_template",
                    "StatusId": "1I005IUOFEZ24SJ62ZSP4PI1BZX88VUL4V1Z",
                    "cust_string_value__gc": "hello"
                },
                "associatedCTAs": [],
                "associatedSPs": [
                    {
                        "gsid": "1S02JJSBDT2ZT78W7N8GO7DU8XPA0RUBHPZ0",
                        "name": "Acc Rel Assoc SP 2",
                        "entityType": "RELATIONSHIP",
                        "ownerId": "1P01J0CQPQSRP90S3XREZGN79WR84S54PAPT",
                        "statusId": "1I004Y368TQW84KNMBX5PGC6I51VPOBJRULN",
                        "dueDate": "2025-01-31 11:30:00",
                        "closedCtaCount": null
                    }
                ]
            }
        ]
    },
    "message": null,
    "localizedMessage": null
}

GET Picklist 

Method

Endpoint URL

/v1/csgoal/external/admin/picklist

Sample Request Body

{
  "entityIds": ["COMPANY"],    // Pass COMAPANY, RELATIONSHIP_TYPE_IDs, ALL_ENTITY or any cobination
  "active": false,             // Pass true for all active picklists
  "includeMetrics": false,     // Pass true for metrics details
  "includeChildPicklist": true, // Pass true for including status details
  "picklistCategory":"GOAL_TYPE"   //cPass GOAL_TYPE (default) or GOAL_STATUS
}

Sample Response Body

{
    "result": true,
    "errorCode": null,
    "errorDesc": null,
    "localizedErrorDesc": null,
    "requestId": "08ae7618-07b4-4657-808d-7d5463a231fb",
    "data": {
        "picklists": [
            {
                "gsid": "1I00GO4Q83RGDEM94YVKZHCWLIHJNZ6NBPWE",
                "name": "Stage xorg validate",
                "color": "#98E7B1",
                "picklistCategory": "GOAL_TYPE",
                "displayOrder": 4,
                "active": true,
                "openStatusType": false,
                "recurring": false,
                "systemDefined": false,
                "associationDetails": {
                    "autoAssignFutureAssociationIds": true,
                    "associationCategory": "ENTITY",
                    "associationIds": [
                        "COMPANY"
                    ]
                },
                "childPicklistIds": {}
            },
            {
                "gsid": "1I00GO4Q83RGDEM94YFZF1JII9BB5FOAUPUA",
                "name": "new goal type with metrics",
                "color": "#98E7B1",
                "picklistCategory": "GOAL_TYPE",
                "displayOrder": 3,
                "active": true,
                "openStatusType": false,
                "recurring": false,
                "systemDefined": false,
                "associationDetails": {
                    "autoAssignFutureAssociationIds": true,
                    "associationCategory": "ENTITY",
                    "associationIds": [
                        "ALL_ENTITY"
                    ]
                },
                "childPicklistIds": {}
            },
            {
                "gsid": "1I00GO4Q83RGDEM94Y417YFL8IB9L9R5WO99",
                "name": "Default",
                "systemName": "DEFAULT_GOAL_TYPE",
                "color": "#98E7B1",
                "picklistCategory": "GOAL_TYPE",
                "displayOrder": 1,
                "active": true,
                "openStatusType": false,
                "recurring": false,
                "systemDefined": true,
                "associationDetails": {
                    "autoAssignFutureAssociationIds": true,
                    "associationCategory": "ENTITY",
                    "associationIds": [
                        "ALL_ENTITY"
                    ]
                },
                "childPicklistIds": {}
            },
            {
                "gsid": "1I00GO4Q83RGDEM94YIQ4HZ6OZGYP2QTVG9K",
                "name": "new goalc hecl",
                "color": "#98E7B1",
                "picklistCategory": "GOAL_TYPE",
                "displayOrder": 5,
                "active": true,
                "openStatusType": false,
                "recurring": false,
                "systemDefined": false,
                "associationDetails": {
                    "autoAssignFutureAssociationIds": true,
                    "associationCategory": "ENTITY",
                    "associationIds": [
                        "ALL_ENTITY"
                    ]
                },
                "childPicklistIds": {}
            }
        ],
        "childPicklists": [],
        "metrics": null
    },
    "message": null,
    "localizedMessage": null

Error Codes 

Error code

 

Error Message

 

Reason

HTTP Status Code

8001

CTA_RECORD_EMPTY

CTA set provided is empty

400

8002

SP_RECORD_EMPTY

Success Plan set provided is empty

400

8007

INVALID_PAGE_REQUEST

Invalid page request

400

8008

INVALID_LOOKUP_CONFIG

Lookup Error

400

8009

INVALID_FIELD

Invalid field in select clause

400

8010

INVALID_STATUS_NAME

Invalid status name provided

400