Legacy retrieval
You are moving to Goodays and your previous partner collected ratings, verbatims, end customer data and custom parameters. You can import this history into Goodays, so that your statistics and KPIs keep their continuity.
Each past participation is sent with one API call. Historical participations only feed your statistics: they never enter the Inbox, raise no alert, send no notification and do not go through Converse. Their verbatims are not analyzed by default: ask your Goodays project contact if you need it (see Live or historical import).
Before you start
- Map your data. Your legacy data will rarely match the Goodays format as is: match each legacy survey and question with a Goodays survey and question, and each legacy point of sale with a Goodays point of sale. This page assumes this transformation is done.
- Plan for volume. The import is simple but can take time for a large history. Send a
collect_uidwith each participation so that you can resume an interrupted import safely. - Test first. Import a small sample, check it with your Goodays project contact, then send the rest.
How to import your history
Call the /responses/historical endpoint with the POST method and the correct payload.
This payload contains the list of all the answers of a participation and, if any, the verbatim of the end customer. In order to create the list of answers, you need to get the surveys and their questions, to match the Goodays questions with the legacy answers.
/responsesis now/responses/historicalThe endpoint has a new, more explicit name:
POST /responses/historical. It takes exactly the same payload and behaves the same way. If you already usePOST /responses, you do not have to change your URL: it remains available.
- Get the surveys
Request the following endpoint: /surveys.
You will obtain something like this:
{
"next": "{next-cursor}",
"previous": "{previous-cursor}",
"results": [
{
"id": "{survey-id}",
"slug": "post-purchase",
"label": "Post Purchase",
"enabled": true,
"detail_url": "https://api.goodays.co/v2/surveys/{survey-id}"
},
{
"id": "{survey-id}",
"slug": "post-appointment",
"label": "Post Appointment",
"enabled": true,
"detail_url": "https://api.goodays.co/v2/surveys/{survey-id}"
}
]
}- For each survey, get the attached questions
Request the following endpoint: /surveys/{survey-id} with a survey ID retrieved from the previous request.
Below, an example of the API response:
{
"id": "{survey-id}",
"slug": "post-purchase",
"label": "Post Purchase",
"enabled": true,
"questions": [
{
"id": "{question-id}",
"position": 1,
"title": "Are you **satisfied** with your purchase in our store ?",
"enabled": true,
"type": "stars",
"enabled_at": "2018-01-18T02:22:22.157859+01:00",
"disabled_at": null,
"options": {},
"sub_questions": []
},
{
"id": "{question-id}",
"position": 2,
"title": "Please rate **the welcome and sympathy** of our team",
"enabled": true,
"type": "stars",
"enabled_at": "2018-01-18T02:22:22.802779+01:00",
"disabled_at": null,
"options": {},
"sub_questions": []
}
],
"places": "https://api.goodays.co/v2/surveys/{survey-id}/places"
}Now that you have retrieved the surveys ids and the questions ids, you can generate the payload to insert your legacy participations in Goodays.
- Create payloads
The payload you need to generate looks like the one below:
{
"place": "{place-id}",
"date": "{date-of-the-participation}",
"survey": "{survey-id}",
"answers": [
{
"value": 10,
"question": "{question-id}"
},
{
"value": 5,
"question": "{question-id}"
}
],
"user": {
"email": "[email protected]",
"first_name": "Mikey",
"last_name": "Walsh",
"phone": "0123456789",
"crm_id": "{crm-id}"
},
"context": {
"{custom-parameter-key}": "{custom-parameter-value}"
},
"message": {
"created_date": "{date-of-the-participation}",
"type": "Praise",
"content": "{verbatim-of-the-end-customer}"
},
"medium": "{medium}",
"collect_uid": "{your-unique-participation-id}"
}
Participation dateYou should fill the
datefield with the date where the participation actually took place!
Custom parametersThe
contextpart contains your custom parameters. To obtain their list, request the following endpoint :/configuration.
VerbatimThe
messagepart is optional. It contains the verbatim of the end customer, with its remark type (Idea,Praise,Problem,QuestionorNoType). A verbatim cannot be sent without theuserobject. See Become a collection source for the details of each field.
Answer valuesThe expected
valueformat depends on the question type: see Surveys & Question Types. For example, a Yes/No question takes1for yes and0for no.
- Send the request
Once your payload is properly built, you can call the endpoint/responses/historicalwith thePOSTmethod.
Don't forget to add your payload!
curl --location --request POST 'https://api.goodays.co/v2/responses/historical' \
--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}
],
"medium": "TE",
"collect_uid": "16814802001BC123"
}'If your payload is valid, you will get a "201: created" back in the header.
If not, an error will be returned in the response of the call, for example:
{
"survey": [
"No resource found for the given value."
]
}
Unique participationThe
collect_uidparameter identifies 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_uidalready exists, a409error is returned and the participation is not recorded.This parameter is not mandatory but strongly recommended: it lets you send the same file again safely if an import is interrupted.
A "201" does not mean the participation is created yetHistorical participations are queued and created a few minutes later. Your payload is checked when you send it (format, point of sale, survey, questions,
collect_uid) and these errors are returned right away. The "201" then confirms that the participation has been accepted in the queue, not that it is already created. A failure during the creation is not returned in the call, so always check the result of your import (step 5).
- Check if everything is ok
A few minutes after your import, every participation you created with this method can be retrieved by calling the /responses endpoint with theGETmethod. You can add filters to this request to obtain the results for an end customer, a point of sale or a survey.
Then you can retrieve each participation to check that it matches your expectations.
Updated 14 days ago