The Response API lets you access the data your surveys collect — on demand and in JSON format — without setting up webhooks or third-party integrations.

👍
Going further
Consult the API Reference for more.

📘
Feel stuck ?
Need help with an error? Head to Troubleshooting and errors for more information.

Key Concepts

With the Response API, you send a GET request each time you want to retrieve your data.

The API response includes all the participations your surveys have received so far, in JSON format. You can also add query parameters to your requests so that the API response only includes participations received after a certain date and time or within a certain date range. The Response API reference lists and describes all of the available query parameters.

The bulk mode returns 20 participations per page by default; use the page_size parameter to get up to 1000 per page (see Pagination).

Use query parameters to retrieve specific data

Suppose you expect thousands of participations on your surveys. To keep your Response API requests manageable, you decide to retrieve your survey's data once each day. In other words, you'll retrieve yesterday's data today, today's data tomorrow, and so on. Because you don't want to retrieve every participation in your surveys, you'll use the start_date and end_date query parameters to narrow the scope of your request and limit the API response by date.

Use start_date and end_date query parameters to retrieve a date range.

Let's assume today is July 10, 2019, and you're going to retrieve the previous day's data. Here's the walkthrough:

You'll still use the GET https://api.goodays.co/v2/responses/bulk endpoint, but don't send your request yet!
Add the start_date query parameter to your request. The start_date parameter is a string that uses ISO 8601 format, Coordinated Universal Time (UTC), with "T" as a delimiter between the date and time. July 10, 2019 at 12:00 a.m. UTC is expressed as 2019-07-10T00:00:00. If you want to retrieve participations for yesterday, 2019-07-09, the value for your start_date query parameter would be 2019-07-09T00:00:00. This means the API response will include participations received since 12:00 a.m. UTC on July 9, 2019.
Add the end_date query parameter to your request. The end_date parameter is also a string in the same format as the start_date parameter. The value for your end_date query parameter would be 2019-07-10T00:00:00. This means the API response will include participations received up until 12:00 a.m. UTC on July 10, 2019.

Here's what the cURL request looks like:

curl --location --request GET 'https://api.goodays.co/v2/responses/bulk? \
	start_date=2019-07-09T00:00:00Z \
  &end_date=2019-07-10T00:00:00Z' \
--header 'Content-Type: application/json' \
--header 'Authorization: {access-token}'

Now, you can send your request. The API response will include only the participations that were submitted yesterday, July 9, 2019. Like this sample:

{
    "next": "https://api.goodays.co/v2/responses/bulk?cursor=cD0yMDE5LTA3LTA5KzE0JTNBNTklM0E0OS42NTM3NjAlMkIwMCUzQTAw&end_date=2019-07-10T00%3A00%3A00Z&start_date=2019-07-09T00%3A00%3A00Z",
    "previous": null,
    "results": [
        {
            "id": "gxKrrlok4o",
            "token": "936d44f4d5a9a95c63b3f0cc7d4642477a9f03836b5efadddd373d114e84c423",
            "created_date": "2019-07-09T17:48:36.222412+02:00",
            "updated_date": "2019-07-09T17:48:36.254510+02:00",
            "google_review_date": null,
            "source": "email",
            "survey": {
                "id": "QOJ85mb8wE",
                "slug": "post_purchase_pos",
                "label": "Post purchase point of sale",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/surveys/QOJ85mb8wE"
            },
            "answers": [
                {
                    "id": "vdJrLvWQdD",
                    "value": 8,
                    "question": {
                        "id": "1vdOBYlA8l",
                        "title": "Would you recommend Style to your friends and family?",
                        "type": "nps",
                        "enabled": true
                    }
                },
                {
                    "id": "y8V20vN28G",
                    "value": 4,
                    "question": {
                        "id": "pe8NzypJ8j",
                        "title": "Are you satisfied with your checkout experience?",
                        "type": "stars",
                        "enabled": true
                    }
                }
            ],
            "message": {
                "id": "58yj9M7qdw",
                "created_date": "2019-07-09T17:48:36.222412+02:00",
                "type": "Problem",
                "content": "I like this shop!",
                "attachment": null,
                "sender": {
                    "email": "[email protected]",
                    "first_name": "George",
                    "last_name": "Abitbol"
                }
            },
            "reply": null,
            "user": {
                "email": "[email protected]",
                "first_name": "George",
                "last_name": "Abitbol",
                "opt_in": {
                    "newsletter": false,
                    "email": false,
                    "sms": false,
                    "custom": false
                }
            },
            "context": {
                "email": "[email protected]",
                "phone": "06123456789",
                "crm_id": "",
                "last_name": "Abitbol",
                "first_name": "George",
                "extra": {
                    "order_id": "12345",
                    "title": "Mademoiselle"
                }
            },
            "place": {
                "id": "5gd0Lz1XdL",
                "partner_id": "142",
                "name": "Style Aix-en-Provence",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/places/5gd0Lz1XdL"
            },
            "delegated_to": null,
            "attached_messages": [],
            "state": "open",
            "thread": "6dn1GnXl8E",
            "actions": {
                "reply": "https://api.goodays.co/api/v2/responses/gxKrrlok4o/reply",
                "spam": "https://api.goodays.co/api/v2/responses/gxKrrlok4o/spam",
                "close": "https://api.goodays.co/api/v2/responses/gxKrrlok4o/close"
            },
            "alert_triggered": false
        },
        {
            "id": "p4MZZJJBx2",
            "token": "ceabc8599d95d926cf617b0fe420c6f975e3f3deb83ced454e22f8e43b87b1b1",
            "created_date": "2019-07-09T16:59:49.653760+02:00",
            "updated_date": "2019-07-09T16:59:49.685842+02:00",
            "google_review_date": "2019-07-09T14:32:10.000000+02:00",
            "source": "google",
            "survey": {
                "id": "9v8XR0X43o",
                "slug": "gmb",
                "label": "Google",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/surveys/9v8XR0X43o"
            },
            "answers": [
                {
                    "id": "vdJrLvWQdD",
                    "value": 5,
                    "question": {
                        "id": "1vdOBYlA8l",
                        "title": "Google rating",
                        "type": "csat",
                        "enabled": true
                    }
                }
            ],
            "message": null,
            "reply": null,
            "user": null,
            "context": {},
            "place": {
                "id": "okxwBz5B4y",
                "partner_id": "049",
                "name": "Style Ajaccio",
                "enabled": true,
                "detail_url": "https://api.goodays.co/v2/places/okxwBz5B4y"
            },
            "delegated_to": null,
            "attached_messages": [],
            "state": "open",
            "thread": null,
            "actions": {},
            "alert_triggered": false
        }
    ]
}

📘
The google_review_date attribute
google_review_date is the date the review was last modified on the Google Business Profile, as returned by Google (its updateTime). For a review that was never edited, it is the date the review was posted. It's populated only for participations where source is google; it's null for every other source.
Use it instead of created_date / updated_date when you need dates consistent with Google-side reporting (e.g. to match daily/weekly counts against the Google Score API or the Google statistics screen in the back office), since created_date / updated_date reflect Goodays' own collection lifecycle, not Google's own dates.

📘
Anonymisation option
An anonymisation option can be enabled on your API token. When it is enabled, participations returned by GET /responses/{id} and GET /responses/bulk that come from your end customers or from external reviews (Google, etc.) are anonymised:

the email, first_name and last_name of the respondent, and of every person who took part in the conversation (including your own pro users), are returned as null;

email, phone, first_name and last_name are returned as null in context;

crm_id and the other context fields are kept, so you can still reconcile participations with your own systems.

The option is enabled per token. Ask your Goodays project contact to activate it.

📘
Parsing the answers array
The structure of the objects inside the answers array depends entirely on the type of question asked (e.g., NPS, CSAT, multiple choice).
To properly parse this data and understand advanced behaviors like conditional logic (mother-daughter questions) or alert triggers, please consult our dedicated guide: Survey Question Types & Structures.

Participation attributes

Each object in the results array represents a single participation. Here are the attributes exposed on it:

Attribute	Type	Description
id	string	Unique identifier of the participation.
token	string	Unique token of the participation.
created_date	datetime	Date the participation was created in Goodays.
updated_date	datetime	Date the participation was last updated (survey continued, pro user replied...).
google_review_date	datetime, nullable	Date the review was last modified on the Google Business Profile, as returned by Google (equals the posting date if the review was never edited). Populated only when `source` is `google`; `null` for every other source.
source	string	Source (collection channel): `email`, `sms`, `google`, `facebook`, `widget`, `tripadvisor`, `wifi`, `terminal`...
survey	object	Survey the participation belongs to (`id`, `slug`, `label`, `enabled`, `detail_url`).
answers	array	Answers given to the survey's questions. See Survey Question Types & Structures.
message	object, nullable	Initial verbatim left by the end customer, if any.
reply	object, nullable	Reply sent by a pro user, if any.
user	object, nullable	End customer identity (`email`, `first_name`, `last_name`, `opt_in`).
user.opt_in	object	Consents given by the end customer to your brand (current state, not specific to this participation). Each value is a boolean: - `newsletter`: subscription to your newsletter; - `email`: agreement to receive your communications by email; - `sms`: agreement to receive your communications by SMS; - `custom`: acceptance of your custom opt-in, the additional consent checkbox with your own wording that can be enabled on your collection widget.
context	object	Custom parameters sent at collection time (`email`, `phone`, `crm_id`, `extra`...). Their list is returned by /configuration.
place	object	Point of sale the participation is attached to (`id` is the Place ID, `partner_id` your external ID, `name`, `enabled`, `detail_url`).
delegated_to	object, nullable	Point of sale the participation was delegated to (usually Customer Service), if any.
attached_messages	array	Private messages exchanged on the same thread after the first reply.
state	string	Current state of the participation: `open`, `closed` or `spam`.
thread	string, nullable	Identifier of the conversation thread.
actions	object	URLs of the actions currently available on the participation (`reply`, `spam`, `call`, `close`), depending on its state.
alert_triggered	boolean	Whether the participation triggered a dissatisfaction alert.

Add some filters

It is possible to add GET parameters to refine the list of participations over a defined period, a point of sale...

GET parameters

To refine the result, it is possible to combine the following GET parameters:

GET parameters	Description
start_date	Start date of the collection period. Format : YYYY-MM-DDThh:mm:ssZ See this page for the timezone management.
end_date	End date of the collection period. Format : YYYY-MM-DDThh:mm:ssZ See this page for the timezone management.
date_field	Choose the date on which the period filter should be set. See chapter Choose the date to filter 💡 We recommend that you systematically use this parameter in your API calls with the value`updated_date` to retrieve all participations that have been modified over the requested `start_date` / `end_date` period, and not just those created.
place	Filter on a point of sale. Place ID from the endpoint /places, or your external ID.
survey	Filter on a survey. See chapter Retrieve the "survey-id"
source	Filter on source (collection channel): "email", "widget", "wifi", "plv", "receipt", "sms", "terminal", "critizr", "sdk", "facebook", "sms_trans", "sms_text", "tripadvisor", "trustpilot", "google", "google_messaging", "pagesjaunes", "outbound_call", "sms_conv", "merci", "google_play_store", "apple_app_store", "uber_eats", "whatsapp", "deliveroo".
email	Filter on the end customer's email (`user.email`). The email sent in `context` is not used.
crm_id	Filter on a CRM ID (aka end customer ID).
first_name	Filter on first name of the end customer.
last_name	Filter on last name of the end customer.
phone	Filter on phone of the end customer.
has_answers	Filter on participations that have a survey answered (completely or partially) by the end customer. Possible values: `true` or `false`.
has_message	Filter on participations that have a verbatim from the end customer. Possible values: `true` or `false`.
has_reply	Filter on participations that have already been replied to by a pro user. Possible values: `true` or `false`.

Retrieve the "survey-id"

Call the endpoint url https://api.goodays.co/v2/surveys to obtain the ID corresponding to the right survey.
Then the "id" attribute is the answer.

Choose the date to filter

A participation includes two dates:

The created_date: the date the participation was created
The updated_date: the date the participation was last updated because the end customer continued to complete the survey, a pro user replied...

To define on which date to base the date filter you have to use the parameter GET date_field with the value updated_date or created_date.

This is important if you don't want to miss any updates from your end customers!

Example of filters

Retrieve the participations with a verbatim that have been replied to by a pro user, on a specific point of sale and survey, and whose source is the website:

curl --location --request GET 'https://api.goodays.co/v2/responses/bulk \
   ?survey=gxKrrlok4o \
   &place=ABC123 \
   &has_message=true \
   &has_answers=true \
   &has_reply=true \
   &source=widget' \
--header 'Content-Type: application/json' \
--header 'Authorization: {access-token}'

Participation retrieval

Going further

Feel stuck ?

Key Concepts

Use query parameters to retrieve specific data

The `google_review_date` attribute

Anonymisation option

Parsing the `answers` array

Participation attributes

Add some filters

GET parameters

Retrieve the "survey-id"

Choose the date to filter

Example of filters

What’s Next

Going further

Feel stuck ?

Key Concepts

Use query parameters to retrieve specific data

The google_review_date attribute

Anonymisation option

Parsing the answers array

Participation attributes

Add some filters

GET parameters

Retrieve the "survey-id"

Choose the date to filter

Example of filters

What’s Next

The `google_review_date` attribute

Parsing the `answers` array