Renewal Center API

Introduction

Renewal Center (RC) helps renewal teams to deeply analyze and accurately forecast their renewal business. Renewal Center enriches CRM data with a predictive customer health score to identify risky customers earlier, as well as avoid missed opportunities and forecasts.

Furthermore, Renewal Center helps CSMs manage and forecast their book of business by enriching Opportunities (from Gainsiht, Salesforce and other CRMs) with Customer Success insights to efficiently manage renewal and related upsell opportunities, recognize risks in a timely fashion, and report on key metrics.

This document explains the following two APIs:

Create Opportunity API: This API is used to create a single opportunity record or bulk opportunity records.
Update Opportunity API: This API is used to update a single opportunity record or bulk opportunity records.

Prerequisites

Ensure that the Renewal Center (RC) package is enabled in your Gainsight environment. RC is available as an add-on in the Essential package and is included in the Enterprise package.

Authorization

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

Once you get your access key, pass it as part of the request header “accesskey” for all of your API requests into Gainsight. The AccessKey does not expire.

Headers

Key	Value
Access Key	For more information on how to generate or share an access key, refer to the Generate REST API Access Key article.
Content Type	JSON

Throttling Limits

API	Rate Limit
Record Limit	200

Create Opportunity API

This API is used to create a single opportunity record or bulk opportunity records.

Method

POST

Endpoint URL

v1/renewals/external-api/opportunity

For example, if your domain URL is as follows:

https://demo-techcomm.gainsightcloud.com/v1/ui/home

Your endpoint URL will be as follows:

https://demo-techcomm.gainsightcloud.com/v1/renewals/external-api/opportunity

Sample Request Body

{
    "resolutionKeys": [],
    "records": [
        {
            "ChurnReason": "Implementation",
            "OpportunityType": "Renewal",
            "ChangeAmount": "2121",
            "Company":"1RX1D22GQ0BW6RRMU7L7OIWE55F9XG09JCKN",
            "ChurnNotes": "<p style=\"text-align: right;\">adaddadac</p>",
            "ChurnTotal": "2121",
            "CloseDate": "26/12/2023",
            "DueDate": "24/12/2023",
            "Stage": "Analysis",
            "Name":"Name"
        },
        {
            "ChurnReason": "Implementation",
            "OpportunityType": "Renewal1",
            "ChangeAmount": "2121",
            "ChurnNotes": "<p style=\"text-align: right;\">adaddadac</p>",
            "ChurnTotal": "2121",
            "CloseDate": "26/12/2023",
            "DueDate": "24.12.2023",
            "Stage": "Analysis"
        }
    ]
}

Note:

Any custom field created by the organization for opportunities is part of the sample responses. A suffix __gc is added to a custom field in the response body.
For example, Total ARR is a custom field with a value of 1000. In the response body, it appears as:
- ```
"TotalARR__gc" : "1000"
```

Parameters

NA: Not applicable.

Parameters	Data Type	Values	Description
Churn Reason	Dropdown List	Competition Cost of Ownership Implementation Lost Champion Low Adoption Overbought Product Issue ROI Not Realized Should Not Have Sold Use Case Change Uncontrollable Other	A dropdown list value that identifies the reason an opportunity churned.
Opportunity Type	Dropdown List	NA	A dropdown list value that identifies the type of opportunity. It is configurable and subject to the organization’s business process.
Change Amount	Currency	NA	A currency value that is calculated as follows: Opportunity (Open) = Forecast Amount - Target Amount Opportunity (Closed Won or Closed Lost) = Final Amount - Target Amount
Company	GSID	NA	A GSID value of Company in Gainsight with an associated opportunity.
Churn Notes	Rich Text Area	NA	A rich text area value that contains churn information of an opportunity.
Churn Total	Currency	NA	A currency value that identifies the total churn amount of an opportunity.
Close Date	Date	NA	A date value that highlights the date when an opportunity is expected to close. This field is synced from CRM where the opportunity is created.
Due Date	Date	NA	A date value that highlights the “Due Date” for a renewal opportunity. This field supports the summary calculation for “Renewals Due” and “Gross Renewal Rate.” This date is used to calculate if a renewal is early or late, as compared to the “Close Date.”
Stage	Dropdown List	NA	A stage value that provides the current stage of an opportunity. This field is synced from CRM where the opportunity is created.
Name	String	NA	A string value that provides the name of an opportunity.This field is synced from CRM where the opportunity is created.
GSID	GSID	NA	A GSID value that provides the unique GSID of the Company to which an opportunity belongs.
Deleted	Boolean	True False	A boolean value that is marked as True or False when an opportunity is deleted. Deleted opportunities are synced from SFDC to Gainsight through Connector.
Description	Rich Text Area	NA	A rich text area that provides description for the opportunity.
DS Forecast Amount	Currency	NA	A currency value that displays the Forecast amount for an opportunity derived through Data Science calculations.
DS Likelihood Score	Number	NA	A number value that displays the probability score of winning an opportunity derived through Data Science calculations.
DS Score Updated At	Date Time	NA	A datetime value that identifies the last time a score was derived by Data Science calculations. When there are any changes in the opportunity, it triggers Data Science to update the score through calculations.
Expected Forecast	Currency	NA	A currency value that is populated by multiplication of Forecast Amount and Probability (%).
External Id	String	NA	A string value that displays the SFDC Id of an opportunity. This field is synced from SFDC.
Final Amount	Currency	NA	A currency value that displays the official amount that the opportunity closed. This amount is compared with the Target Amount for closed opportunities to calculate if a renewal has increased in value (upsell) or reduced in value (downsell).
Forecast Amount	Currency	NA	A currency value that displays the Forecasted Annual Recurring Revenue (ARR) or Monthly Recurring Revenue (MRR) amounts.
Forecast Category	Dropdown List	NA	A dropdown value that helps identify the forecast category to which an opportunity stage is associated, as defined in the system.
GS Booking Type	Dropdown List	Renewal Upsell Downsell	A dropdown value that helps to identify whether an opportunity is of Renewal, Upsell, or Downsell type.
Has Line Item	Boolean	True False	A boolean value that marks whether an Opportunity is a current line item or not.
Inferred Booking Type	Dropdown List	Renewal Upsell Downsell Renewal with Upsell Renewal with Downsell	A dropdown list value that displays the specific booking type of an opportunity.
Next Step	Rich Text Area	NA	A rich text area value that provides a description of the next task in closing opportunity.
Opportunity Owner	GSID	NA	A GSID value that identifies the user who has created an opportunity.
Probability (%)	Percentage	NA	A percentage value that displays the probability associated with each opportunity stage.
Record Type	GSID	NA	A GSID value that helps to control the set of opportunity stages. For example, a set of opportunity stages can include Renewal, Upsell, Downsell. The record types are synced from the CRM used by the organization.
Target Amount	Currency	NA	A currency value that is the target renewal dollar amount for opportunity. This field supports the summary calculation for “Renewals Due.”
Type	Dropdown List	NA	A dropdown list value that identifies the type of opportunity. For example, Existing Business or New Business.
Source Type	String	OPPORTUNITY CSQL	A string value that identifies whether the opportunity is created from the Renewal Center feature or Customer Success Qualified Leads feature.
Opportunity Source	String	CONNECTOR RULES COCKPIT RENEWAL_CENTER_UI GS_HOME_FORECAST GS_HOME_CSQL_OPPORTUNITY C360_FORECAST C360_CSQL_OPPORTUNITY R360_CSQL_OPPORTUNITY EXTERNAL_API, GS_HOME UNKNOWN	A string value that identifies the module from where the opportunity is created. This field is ready-only and not editable. For any opportunity created using Connectors from any external CRMs, the value in this field is populated as CONNECTOR_{CRM Name}. For example, for an opportunity created from an SFDC Connector job, the value is populated as "CONNECTOR_SFDC".

Sample Success Response

{
                "record": {
                    "Company": "1RX1D22GQ0BW6RRMU7L7OIWE55F9XG09JCKN",
                    "ChurnReason": "Implementation",
                    "Gsid": "1RX1D22GQ0BW6RRMU7IBOU241RT6NL81XOPZ",
                    "ChurnTotal": "2121",
                    "CloseDate": "26/12/2023",
                    "Name": "Name",
                    "ChangeAmount": "2121",
                    "Stage": "Analysis",
                    "DueDate": "24/12/2023",
                    "OpportunityType": "Renewal",
                    "ChurnNotes": "<p style=\"text-align: right;\">adaddadac</p>"
                },
                "status": "SUCCESS",
                "errors": null,
                "operation": "CREATE"
            }

Sample Failure Response

{
                "record": {
                    "ChurnReason": "Implementation",
                    "Gsid": null,
                    "ChurnTotal": "2121",
                    "ChangeAmount": "2121",
                    "Stage": "Analysis",
                    "DueDate": "24.12.2023",
                    "OpportunityType": "Renewal1",
                    "CloseDate": "26/12/2023",
                    "ChurnNotes": "<p style=\"text-align: right;\">adaddadac</p>"
                },
                "status": "FAILURE",
                "errors": [
                    {
                        "field": "OpportunityType",
                        "invalidValue": "Renewal1",
                        "errorCode": null,
                        "errorMessage": "The Renewal1 picklist value has not been found in OpportunityType column."
                    }
                ],
                "operation": "CREATE"
            }

Update Opportunity API

This API is used to update a single opportunity record or bulk opportunity records.