Met de Tevreden API kun je het hele traject van tevredenheidsonderzoek automatiseren. Van uitnodigen tot het ophalen van resultaten. Maar hoe werkt dat nou in de praktijk? Hieronder volgt een stapsgewijze praktijkgerichte uitleg, inclusief kant en klare voorbeelden.
Voordat je begint, lees de documentatie door, hier staan alle functionaliteiten tot in detail omschreven:
Om de API te implementeren zal er altijd enig programmeerwerk nodig zijn. Om de API uit te testen zijn er enkele tools beschikbaar die het makkelijk maken om API requests te testen. Een van de handigste is de gratis tool Postman. Een alternatieve tool voor de command line is curl.
We hebben ook een Python script gemaakt, welke je vrij kunt gebruiken en aanpassen: https://build.tevreden.io/tevreden/evaluation-api-python-example.
Om de API te gebruiken heb je een API account nodig. Hierbij hoort een "Tevreden-API-key" op een "Tevreden-platform". Deze gegevens ontvang je van Tevreden. De API-key en het platform dienen met elk verzoek aan de API meegestuurd te worden, in de vorm van HTTP headers. In deze voorbeelden gebruiken we "voorbeeldapikey" en "voorbeeldplatform", bij echte calls dien je deze dus te vervangen door de juiste key en het platform.
Met deze call haal je een overzicht op van alle questionnaires die aan het account hangen. In Postman ziet deze call er als volgt uit:
In python kan dit er zo uitzien:
import http.client
conn = http.client.HTTPSConnection("api.tevreden.nl")
headers = {
'tevreden-api-key': "voorbeeldapikey",
'tevreden-platform': "voorbeeldplatform",
'cache-control': "no-cache",
}
conn.request("GET", "/questionnaires", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
De ruwe http call is als volgt:
GET /questionnaires HTTP/1.1
Host: api.tevreden.nl
tevreden-platform: voorbeeldplatform
tevreden-api-key: voorbeeldapikey
Cache-Control: no-cache
Het antwoord (in JSON formaat) kan er dan zo uitzien:
{
"questionnaires": [
{
"organisationid": "voorbeeld_org",
"subject": "01 Evaluatie klanttevredenheid",
"active": 1,
"name": "01 Evaluatie klanttevredenheid",
"attributes": {
"QuestionnaireSubjectWebsite": "01 Evaluatie klanttevredenheid",
"PublicResults": "1"
},
"id": "1662",
"locationid": "voorbeeld_vest",
"nr_reactions": "127",
"holdingid": null
},
{
"organisationid": "voorbeeld_org",
"subject": "02 Evaluatie medewerkerstevredenheid",
"active": 1,
"name": "02 Evaluatie medewerkerstevredenheid",
"attributes": {
"QuestionnaireSubjectWebsite": "02 Evaluatie medewerkerstevredenheid",
"PublicResults": "1"
},
"id": "1663",
"locationid": "voorbeeld_vest",
"nr_reactions": "21",
"holdingid": null
}
]
}
We hebben hier dus twee vragenlijsten die we kunnen gebruiken.
Door middel van het endpoint /invitations kunnen we respondenten uitnodigen.
We willen nu een aantal klanten uitnodigen om de klanttevredenheids-vragenlijst in te vullen. In het antwoord van de vorige call zien we dat het "id" van deze vragenlijst 1662 is. Dit id hebben we nodig in de volgende calls.
Voor een uitnodiging zijn in de meeste gevallen een aantal velden benodigd. In het geval van een email-uitnodiging is dat in ieder geval het veld "email" met daarin het emailadres van de respondent. Daarnaast kunnen er nog andere velden nodig zijn, bijvoorbeeld voor de personalisatie van de email. Voor een lijst van alle velden gebruiken we de call /invitations/questionnaire/{questionnaireid}/fields
De call:
GET /invitations/questionnaire/1662/fields HTTP/1.1
Host: api.tevreden.nl
tevreden-platform: voorbeeldplatform
tevreden-api-key: voorbeeldapikey
Cache-Control: no-cache
Het antwoord:
{
"fields": [
{
"type": "text",
"desc": "aanhef",
"required": 0,
"name": "aanhef"
},
{
"type": "text",
"desc": "achternaam",
"required": 0,
"name": "achternaam"
},
{
"name": "email",
"required": 1,
"desc": "email",
"type": "text"
},
]
}
We zien hierboven dat het veld "email" inderdaad verplicht is en dat daarnaast de velden "achternaam" en "aanhef" gevraagd worden. Als deze laatste twee niet meegestuurd worden zal alles wel gewoon werken, maar de uitnodigingsmail zal minder persoonlijk zijn.
We weten nu precies wat we nodig hebben voor een uitnodiging. We hebben het questionnaireid en de benodigde velden per respondent. We willen ook meteen een herinnering inplannen, indien de respondent niet binnen 5 dagen reageert.
POST /invitations/questionnaire/1665?queue_reminder=1 HTTP/1.1
Host: api.tevreden.nl
tevreden-platform: voorbeeldplatform
tevreden-api-key: voorbeeldapikey
Cache-Control: no-cache
{
"recipients": [
{
"email": "test1@example.org",
"achternaam": "Jansen",
"aanhef": "Geachte heer",
},
{
"email": "test2@example.org",
"achternaam": "Pietersen",
"aanhef": "Geachte mevrouw",
}
]
}
In het antwoord zien we dat alles is goedgegaan, er zijn 2 uitnodigingen en 2 bijbehorende herinneringen aangemaakt:
{
"success": 1,
"message": "Request processed, 2 invitation(s) and 2 reminder(s) created.",
"created": [
{
"reminder_date": "2017-11-19 16:09:21",
"message": "The invitation has been queued for sending at 2017-11-14 16:09:21.",
"questionnaire": {
"id": "1665",
"attributes": {
"QuestionnaireSubjectWebsite": "01 Evaluatie klanttevredenheid",
"PublicResults": "1"
},
"locationid": "voorbeeld_vest",
"active": 1,
"name": "01 Evaluatie klanttevredenheid",
"subject": "01 Evaluatie klanttevredenheid",
"organisationid": "voorbeeld_org"
},
"send_date": "2017-11-14 16:09:21",
"recipient": {
"email": "test1@example.org",
"achternaam": "Jansen"
"aanhef": "Geachte heer",
}
},
{
"reminder_date": "2017-11-19 16:09:21",
"message": "The invitation has been queued for sending at 2017-11-14 16:09:21.",
"questionnaire": {
"id": "1665",
"attributes": {
"QuestionnaireSubjectWebsite": "01 Evaluatie klanttevredenheid",
"PublicResults": "1"
},
"locationid": "voorbeeld_vest",
"active": 1,
"name": "01 Evaluatie klanttevredenheid",
"subject": "01 Evaluatie klanttevredenheid",
"organisationid": "voorbeeld_org"
},
"send_date": "2017-11-14 16:09:21",
"recipient": {
"email": "test2@example.org",
"achternaam": "Pietersen"
"aanhef": "Geachte mevrouw",
}
}
],
"not_created": []
}
De uitnodigingen worden automatisch op de aangegeven tijd verstuurd naar de respondent. De respondent klikt de link aan, en vult de vragenlijst in.
Voor het uitnodigen van klanten of medewerkers is het vaak belangrijk om een herinnering uit te laten sturen naar de personen die je uitnodigt. Omdat dit via de API niet vanzelfsprekend is, is het belangrijk om tenminste 1 van de volgende opties mee te nemen in de calls die je doet naar onze API:
queue_reminder=1
meegeven in de call die je doet. Bijvoorbeeld https://api.tevreden.nl/invitations/questionnaire/{questionnaireid}?queue_reminder=1reminder_date
(herinneringsdatum) meesturen. Dit kan een letterlijke datum zijn of een van de volgende opties onder de volgende link.Wanneer de reacties binnen zijn en goedgekeurd, dan kunnen deze ook via de API opgehaald worden. Dit kan per reactie:
Request:
GET /reactions/questionnaire/1662 HTTP/1.1
Host: api.tevreden.nl
tevreden-platform: voorbeeldplatform
tevreden-api-key: voorbeeldapikey
Cache-Control: no-cache
Response:
{
"total": 2,
"reactions": [
{
"id": "6529",
"date": "2017-11-15 14:09",
"status": 1,
"location": {
"organisationname": "Voorbeeld organisatie",
"name": "Voorbeeld vestiging",
"id": "voorbeeld_vest",
"organisationid": "voorbeeld_org"
},
"summary": {
"question_subjects": {
"De service": 5.0,
"De winkel": 3.8,
"De kwaliteit van het product": 4.5
},
"grade": "9",
"recommendation": 9,
"review": "Uitstekend geholpen!"
},
"source": "email",
"nr": 2,
"recipient": {
"id": "17052"
},
"moderation_date": "2017-11-15 16:01:37",
"organisationid": "Demo_01",
"questionnaire": {
"id": "1665",
"subject": "01 Evaluatie klanttevredenheid"
}
},
{
"id": "6518",
"date": "2017-11-15 10:34",
"status": 1,
"location": {
"organisationname": "Voorbeeld organisatie",
"name": "Voorbeeld vestiging",
"id": "voorbeeld_vest",
"organisationid": "voorbeeld_org"
},
"summary": {
"question_subjects": {
"De service": 3.5,
"De winkel": 4.5,
"De kwaliteit van het product": 4.0
},
"grade": "8",
"recommendation": 8,
"review": "De koffie was lekker."
},
"source": "email",
"nr": 2,
"recipient": {
"id": "17050"
},
"moderation_date": "2017-11-15 15:59:27",
"organisationid": "Demo_01",
"questionnaire": {
"id": "1665",
"subject": "01 Evaluatie klanttevredenheid"
}
}
]
}
Of geagreggeerd:
Request:
GET /results/questionnaire/1665 HTTP/1.1
Host: api.tevreden.nl
tevreden-platform: voorbeeldplatform
tevreden-api-key: voorbeeldapikey
Cache-Control: no-cache
Response:
{
"results": {
"num_reactions": "2",
"questionnaireid": "1665",
"grade": "8.5"
}
}