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
Throttling Limits
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" }
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 |