Customer Goals 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"
}

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