Skip to main content
Gainsight Inc.

Customer Goals APIs

  1. Last updated
  2. Save as PDF 
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"
}

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

 

 

  1. Back to top
  • Was this article helpful?

Recommended articles

  1. Article type
    Topic
    Draft Workflow
    Draft
  2. Tags
    1. Create Customer Goals API
    2. Customer Goals API
    3. Fetch Customer Goals API
    4. Update Customer Goals API