Become a collection source

The Collect API will allow you to become your own collection source by allowing you to send us the collected entries from your own tools!

👍

Going further

Consult the API Collect for more.

📘

Feel stucked?

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

Presentation

The Collect API allows you to push the collected responses on your side from your own tools, all in real time!
Our recommendation is to create participation on the Goodays side as soon as you collect it from your tool. This allows the local manager not to lose time on the processing of the customer feedback.

This is very effective if you are using an application, kiosk or terminal that would not be compatible with the SDKs provided by default by Goodays.

❗️

The survey used is in Goodays format and must respect the response formatting rules.

How to push the responses from my end customer

Push a response

In order to complete the payload to post a response you must first recover the following Goodays data:

And, of course, the data related to the end customer.

You now have all the information you need to post a response to Goodays!
For this you must use the API Collect.

❗️

Unique Response

Be careful to push only one response per end customer's participation: the Collect API records each call you made without deduplication.

For our example, we will send the answer to the survey with the following information (see prepare the data chapter):

  • End customer (the "user") : Mr Miyagi
  • Establishment (the "place") : VÉLO Antibes (ID : ABC123)
  • Survey : post_visit (ID : mrY4WLpx9w)
  • Custom Parameters : Order date (key : ordr_dt)

Description of the payload:

AttributDescriptionMandatory
dateDate of response from the end customer

Format: 2020-08-07T01:29:30.034195+02:00
Yes
userContains the data of the end customer:

- email
- first_name
- last_name
- phone
- crm_id
See The customer parameters part.
contextThe Custom ParametersSee The customer parameters part.
placeThe establishment ID
Enter your establishment code directly here
Yes
surveyThe survey ID

See The survey part.
Yes
answers List of answers to survey questions.

See The survey part.

Note: An end customer is not forced to answer all questions, you can send a survey that is not completed in its totality.
Yes
messageText message from the end customer:

- created_date : format "2020-08-07T01:29:30.034195+02:00"

- type: "Idea", "Praise", "Problem", "Question" or "NoType" if no category exists

- content: text messageNotes:

- A text message cannot be sent without a survey

- A text message must have all his attributes filled in
No
mediumSource of feedback collection.

Here are the most used mediums:

- transactional email: TE
- transactional SMS: TS
- mobile: MOBThe value differs according to your collection perimeter: please ask your Goodays technical contact for this information if it does not match the examples above.
Yes
collect_uidAllows the management of the unique participation.

The collect_uid parameter is used to identify the participation in a unique way. This can be a string, a number, a date... You can, for example, concatenate an order ID, a reservation ID, a basket ID... with a timestamp. The most important thing is that this value must be unique.

If the value of the collect_uid already exists then a 409 error is returned and the response is not recorded.

This parameter is not mandatory but strongly recommended.
No

The API Call:

curl --location --request POST 'https://api.goodays.co/v2/responses/collect' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd' \
--data-raw '{
  "date": "2020-08-07T01:29:30.034195+02:00",
  "user": {
    "email": "[email protected]",
    "first_name": "Kesuke",
    "last_name": "Miyagi",
    "phone": "+33123456789",
    "crm_id": ""
  },
  "context": {
    "ordr_dt": "2020-08-06"
  },
  "place": "kvdAqqMYdj",
  "survey": "mrY4WLpx9w",
  "answers": [
    {"question": "rY4WDG1px9", "value": 5},
    {"question": "ap4Mzm1vx2", "value": 3},
    {"question": "9v8XaO1Xd3", "value": [
                            "Welcome / friendliness",
                            "Availability"]
                            },
    {"question": "5gd0vbRYxL", "value": 2},
    {"question": "OD82OVbJdW", "value": ["Tastes too bland"]},
    {"question": "Qr43JKNjdV", "value": 5},
    {"question": "MexGzQOn4K", "value": 10}
    ],
  "message": {
    "created_date": "2020-09-25T16:13:09.799615+02:00",
    "type": "Praise",
    "content": "I really appreciated my experience with your counselor."
  },
  "medium": "terminal",
  "collect_uid": "16814802001BC123"
}'

If the answer has been recorded, you will get a "201: created" back in the header.
If not, an error will be returned in the endpoint return, for example:

{
    "survey": [
        "No resource found for the given value."
    ]
}

Prepare the data

The survey part

Request the following endpoint : /surveys.

curl --location --request GET 'https://api.goodays.co/v2/surveys' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd'

You will obtain something like this:

"next": null,
    "previous": null,
    "results": [
        {
            "id": "mrY4WLpx9w",
            "slug": "post_visit",
            "label": "Post Visite",
            "enabled": true,
            "detail_url": "https://api.goodays.co/v2/surveys/mrY4WLpx9w"
        },
        {
            "id": "kegxKlZ8oY",
            "slug": "sollicited_new_customer",
            "label": "Email - Post-achat Magasin 1er achat",
            "enabled": true,
            "detail_url": "https://api.goodays.co/v2/surveys/kegxKlZ8oY"
        },
        {
            "id": "LAEd7lD493",
            "slug": "spontaneous",
            "label": "Spontané",
            "enabled": true,
            "detail_url": "https://api.goodays.co/v2/surveys/LAEd7lD493"
        }
    ]
}

Take the id corresponding to the survey you wish to push responses to.
Request the following endpoint : /surveys with the "id" as parameter:

curl --location --request GET 'https://api.goodays.co/v2/surveys/mrY4WLpx9w' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd'

You will obtain something like this:

{
    "id": "mrY4WLpx9w",
    "slug": "restaurant-experience",
    "label": "Restaurant Experience",
    "enabled": true,
    "questions": [
        {
            "id": "rY4WDG1px9",
            "position": 1,
            "title": "Are you generally satisfied with your restaurant experience?",
            "enabled": true,
            "type": "stars",
            "enabled_at": "2019-04-04T17:50:06.349126+02:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": []
        },
        {
            "id": "ap4Mzm1vx2",
            "position": 2,
            "title": "What did you think of the quality of service throughout your meal?",
            "enabled": true,
            "type": "stars",
            "enabled_at": "2019-04-04T17:50:06.416521+02:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": [
                {
                    "id": "9v8XaO1Xd3",
                    "sub_id": 1,
                    "triggers": [
                        1,
                        2,
                        3
                    ],
                    "title": "What can we improve?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2019-04-04T17:50:06.465984+02:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "Welcome / friendliness",
                            "Availability",
                            "Politeness",
                            "Tips",
                            "Errors in the dishes served",
                            "Unsatisfied requests",
                            "Slow service",
                            "Something else."
                        ]
                    }
                }
            ]
        },
        {
            "id": "5gd0vbRYxL",
            "position": 3,
            "title": "Was your meal tasty?",
            "enabled": true,
            "type": "stars",
            "enabled_at": "2019-04-04T17:50:06.507387+02:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": [
                {
                    "id": "OD82OVbJdW",
                    "sub_id": 1,
                    "triggers": [
                        1,
                        2,
                        3
                    ],
                    "title": "What can we improve?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2019-04-04T17:50:06.548106+02:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "Tastes too bland",
                            "Seasoning",
                            "Problem cooking meat",
                            "Warmth of the dishes",
                            "Freshness of the products",
                            "Originality of taste",
                            "Something else."
                        ]
                    }
                }
            ]
        },
        {
            "id": "Qr43JKNjdV",
            "position": 4,
            "title": "How do you judge the quality/price ratio of your dish?",
            "enabled": true,
            "type": "stars",
            "enabled_at": "2019-04-04T17:50:06.586386+02:00",
            "disabled_at": null,
            "options": {},
            "sub_questions": [
                {
                    "id": "k6xmZ1vK8j",
                    "sub_id": 1,
                    "triggers": [
                        1,
                        2,
                        3
                    ],
                    "title": "What can we improve?",
                    "enabled": true,
                    "type": "multiple_answers",
                    "enabled_at": "2019-04-04T17:50:06.630313+02:00",
                    "disabled_at": null,
                    "options": {
                        "choices": [
                            "Portion size",
                            "Quality of the meat",
                            "Quality of other products",
                            "Something else."
                        ]
                    }
                }
            ]
        },
        {
            "id": "MexGzQOn4K",
            "position": 5,
            "title": "Would you recommend Buffalo Grill to others?",
            "enabled": true,
            "type": "nps",
            "enabled_at": "2019-04-04T17:50:06.674478+02:00",
            "disabled_at": null,
            "options": {
                "alert_limit": 6
            },
            "sub_questions": []
        }
    ],
    "places": "https://api.critizr.com/v2/surveys/kQvdJyo8Dg/places",
    "responses": "https://api.critizr.com/v2/surveys/kQvdJyo8Dg/responses"
}

That's it, you have the structure of the survey!

👍

Types of questions

All of these answer type are compatible with the Collect API :

  • nps
  • csat
  • stars
  • choices
  • multiple_answers
  • text

The customer parameters part

Request the following endpoint : /configuration.

curl --location --request GET 'https://api.goodays.co/v2/configuration' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd'

You will obtain something like this:

{
    "custom_parameters": [
        {
            "key": "first_name",
            "label": "First name",
            "required": false,
            "use_in_stats": true
        },
        {
            "key": "email",
            "label": "Email",
            "required": false,
            "use_in_stats": true
        },
        {
            "key": "phone",
            "label": "Phone",
            "required": false,
            "use_in_stats": false
        },
        {
            "key": "last_name",
            "label": "Last name",
            "required": false,
            "use_in_stats": false
        },
        {
            "key": "crm_id",
            "label": "ID Client",
            "required": false,
            "use_in_stats": false
        },
        {
            "key": "ordr_dt",
            "label": "Order date",
            "required": false,
            "use_in_stats": false
        },
        {
            "key": "advsr",
            "label": "Adivsor seen",
            "required": false,
            "use_in_stats": true
        }
    ]
}

🚧

What Custom Parameters do I have to use?

To find out if a Custom Parameter is mandatory you have to look at the attribute "required ". If it is at "true" then the attribute must be in the payload of the API call.

🚧

And for the "user"?

For the user object: if a value is optional you must leave the attribute with an empty value.

But the name and first_name is always mandatory: if you don't have it you must be don't push the user object.

Examples

Send survey scores only

curl --location --request POST 'https://api.goodays.co/v2/responses/collect' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd' \
--data-raw '{
  "date": "2020-08-07T01:29:30.034195+02:00",
  "user": {
    "email": "[email protected]",
    "first_name": "Kesuke",
    "last_name": "Miyagi",
    "phone": "+33123456789",
    "crm_id": "012ABC789"
  },
  "context": {
    "ordr_dt": "2020-08-06"
  },
  "place": "ABC123",
  "survey": "mrY4WLpx9w",
  "answers": [
    {"question": "rY4WDG1px9", "value": 5},
    {"question": "ap4Mzm1vx2", "value": 3},
    {"question": "9v8XaO1Xd3", "value": [
                            "Welcome / friendliness",
                            "Availability"]
                            },
    {"question": "5gd0vbRYxL", "value": 2},
    {"question": "OD82OVbJdW", "value": ["Tastes too bland"]},
    {"question": "Qr43JKNjdV", "value": 5},
    {"question": "MexGzQOn4K", "value": 10}
    ],
  "medium": "terminal",
  "collect_uid": "16814802001BC123"
}'

Send a partially completed survey

curl --location --request POST 'https://api.goodays.co/v2/responses/collect' \
--header 'Content-Type: application/json' \
--header 'Authorization: 1234abcd1234abcd1234abcd1234abcd' \
--data-raw '{
  "date": "2020-08-07T01:29:30.034195+02:00",
  "user": {
    "email": "[email protected]",
    "first_name": "Kesuke",
    "last_name": "Miyagi",
    "phone": "+33123456789",
    "crm_id": "012ABC789"
  },
  "context": {
    "ordr_dt": "2020-08-06"
  },
  "place": "ABC123",
  "survey": "mrY4WLpx9w",
  "answers": [
    {"question": "rY4WDG1px9", "value": 5},
    {"question": "ap4Mzm1vx2", "value": 3}
    ],
  "medium": "terminal",
  "collect_uid": "16814802001BC123"
}'