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:
- the structure ID of the survey
- the question IDs of the survey
- the establishment ID
- the Custom parameters
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:
| Attribut | Description | Mandatory |
|---|---|---|
| date | Date of response from the end customer Format: 2020-08-07T01:29:30.034195+02:00 | Yes |
| user | Contains the data of the end customer: - first_name - last_name - phone - crm_id | See The customer parameters part. |
| context | The Custom Parameters | See The customer parameters part. |
| place | The establishment ID Enter your establishment code directly here | Yes |
| survey | The 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 |
| message | Text 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 message Notes: - A text message cannot be sent without a survey - A text message must have all his attributes filled in | No |
| medium | Source 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_uid | Allows 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 :
npscsatstarschoicesmultiple_answerstext
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.
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"
}'
Updated 2 months ago