TABLE OF CONTENTS


 

API Setup

Choose your Host Region to have the documentation adapt to your use case.


Host Region
LabelValue
EUeu
USus
AUau






Business Use Case

The GET Responses API is used to request responses from your CustomerGauge system. All responses returned will contain a base set of data, and can be expanded with Drivers, Additional Questions, Tags/Topics, and Segment data. This is ideal to populate your data lake on a daily basis.






How to use


How to call

This API is designed to be used to populate a data lake. As such, there are two times when you'd want to call the API:

  • Initially: when you start out, and you want to populate your data lake with all your CustomerGauge Survey Responses.
  • Periodically: after you have done the initial population, you'd want to keep it up to date with any new CustomerGauge Survey Responses.


How to call initially

When you're starting out, you make your first call without a cursor parameter, and a per_page=1000 parameter. Store the cursor value that gets returned from this first call in a permanent place. Then call the API again, passing the cursor value in the cursor parameter. Repeat this process until you have received all your responses (you're done when the "data" array is empty).


How to call periodically

After you've done the initial load, you'd want to set up a periodic process to keep your data lake in sync. Call the API with the cursor you have stored during the initial load. Store the cursor that gets returned, like you did during the initial load. You can repeat this process periodically (hourly, daily, weekly, etc.). The most frequent intended use is hourly - if you need responses more frequently, use Outgoing Webhooks instead.


Traversing the data set

Each response will contain a Cursor that you can use to call the next data set. You can store the cursor and call the API the next time, using the stored cursor to get the latest data.






Good to Know

Up to 1000 responses are returned per page and ordered by our internal primary key, oldest first. The request will also return a cursor parameter value which is used to navigate to next page or previous page.






Authentication

OAuth2 Authentication is used to connect to this API. In order to create the Authentication, which is needed to generate the Access Token, Administrator access to CustomerGauge is needed. Once you've created your Authentication, you can acquire a Bearer Access Token by calling our OAuth2/Token API:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials&client_id={{ Client ID }}&client_secret={{ Client Secret }}"
https://auth.{{ apiRegion }}.customergauge.com/oauth2/token


The acquired Bearer Access Token is used in the Authorization header in your API request.


Note: The Access Token is only valid for up to 1 hour. Save the Access Token temporarily when calling the API multiple times in a row, or obtain a fresh Access Token before calling the API.






Endpoint

Endpoint URL

https://api.{{ apiRegion }}.customergauge.com/v7/rest/sync/responses






Request


Parameters

KeyDescriptionRulesExample
per_pageDefines the amount of responses returned per page.Number from 1 to 1000.per_page=100
cursorParameter value returned from the API to navigate pages. The cursor is an integer.Value is returned from the API.cursor=123
with[]Defines additional information to be returned by the API, under the same key.

selected_drivers - returns the reasons for the NPS Score.

tags - returns Manual Tags and Feedback AI Topics with sentiment.

questions - returns additional questions, CES, CSAT and Rating questions and their answers.

properties - returns segment information about the Survey Record.

salutation - returns the value saved in the salutation field.

rand_value - returns the order value of the record.

followup_ai_suggestion - returns the follow-up suggestion from the Close the Loop assistant.		"selected_drivers", "tags", "questions", "properties", "salutation", "followup_ai_suggestion", and/or "rand_value".with[]=selected_drivers&with[]=tags
number_customergaugeFilters a specific CGID.Numbersnumber_customergauge=45778
filterFilters the data using the Outbound filter setup.Value is the reference provided in Outbound filter setup.filter=147b3662-cd7e-490c-b865-9be3480ca2fd
period[field]Specifies the date type which will be returned.Values: date_creation; date_order; date_sent; date_survey_response.period[field]=date_creation
period[start]Defines the period start date.yyyy-mm-dd format.period[start]=2023-01-05
period[end]Defines the period end date. yyyy-mm-dd format.period[end]=2023-01-25




Example Request

https://api.{{ apiRegion }}.customergauge.com/v7/rest/sync/responses?per_page=25






Response


Date filters

When filtering by dates, the system will pull data from the first to the last second of the start and end dates, respectively.



Time zone

Note: The dates and times displayed in the response are based on your System Timezone. You may check your system's time zone in the Sending step of a Campaign in Campaign Suite.



Status values

The status field returns the last known status of the survey record. Due to the nature of statuses, more statuses could be introduced over time, without prior notice. New statuses will always be less than 128 bytes long.

Current statuses available - `response` or `partial-response`



Response Body

HTTP Status CodeDescription
200OK - everything worked as expected.

Example Response Body
{
"data": [
        {
            "status": "response",
            "contact": {
                "first_name": "John",
                "last_name": "Doe",
                "salutation": "Mr."
            },
            "account": {
                "name": "ACME",
                "number": "123"
            },
            "number_customergauge": 3414,
            "number_customer": "123",
            "number_order": "321",
            "email": "example@customergauge.com",
            "phone": "1234567890",
            "nps": 10,
            "comment": {
                "original": "Comentário de exemplo",
                "translation": "Example Comment"
            },
            "date_creation": "2022-03-30 12:34:56",
            "date_order": "2022-03-30 12:34:56",
            "date_sent": "2022-03-30 12:34:56",
            "date_survey_response": "2022-03-30 12:34:56",
            "language": "EN",
            "locale": "en_GB",
            "follow_up": {
                "requested": false,
                "details": "1234567890"
            },
            "date_email_sent": "2022-03-30 12:34:56",
            "rand_value": "5800",
            "tags": [
                {
                    "label": "Product",
                    "type": "topic",
                    "sentiment": "mixed"
                },
                {
                    "label": "Support",
                    "type": "tag"
                }
            ],
            "questions": [
                {
                    "title": "We made it easy to solve your support issue.",
                    "answer": "7"
                }
            ],
            "selected_drivers": [
                {
                    "primary": "Ordering",
                    "secondary": [
                        "Ease of Ordering",
                        "Product Information",
                        "Invoicing/Payments"
                    ]
                },
                {
                    "primary": "Product",
                    "secondary": [
                        "Ease of Use",
                        "Capabilities",
                        "Return on Investment"
                    ]
                }
            ],
            "properties": [
                {
                    "field": "Country",
                    "reference": "NL"
                },
                {
                    "field": "Division",
                    "reference": "Global"
                },
                {
                    "field": "Touchpoint",
                    "reference": "Relationship"
                },
                {
                    "field": "Key Contact",
                    "reference": null
                },
                {
                    "field": "Segment A",
                    "reference": null
                },
                {
                    "field": "Account Manager",
                    "reference": null
                }
            ],
            "followup_ai_suggestion": "Dear [Respondent],\n\nThank you for taking the time to complete our survey and for giving us a perfect score of 10! We are thrilled to hear that you would highly recommend our service performance, products, and professional services/implementation.\n\nYour kind words about our team's helpfulness, professionalism, and quick issue resolution are greatly appreciated. We strive to provide a dedicated and friendly approach in all our interactions, and it is wonderful to know that this has made your experience a great one.\n\nIf you have any further feedback or need assistance in the future, please do not hesitate to reach out. Thank you once again for your valuable input and continued support.\n\nBest regards,"
        }
    ],
    "cursor": {
        "next": 123
    }
}


primary 

401The Access Token obtained has expired, or is invalid. Call the Authenticate API again to obtain a new Access Token.

Example Response Body
{
    "message": "Unauthenticated."
}







How to know the Data Set for your system?







Examples

cURL example

curl --location --request GET 'https://api.{{ apiRegion }}.customergauge.com/v7/rest/sync/responses' \
--header 'Authorization: Bearer XXXXX' \
--header 'Content-Type: application/json' \



Not the API you're looking for?

Get an overview of our APIs here.