Handleiding Tevreden API
Met de Tevreden API op https://api.tevreden.nl kun je het hele traject van tevredenheidsonderzoek automatiseren. Van uitnodigen tot ophalen van resultaten. Maar hoe werkt dat nou in de praktijk? Hieronder volgt een stapsgewijze praktijkgerichte uitleg, inclusief kant en klare voorbeelden.
Handige tools
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 2. Een alternatieve tool voor de command line is curl.
Authenticatie
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.
Een eerste API Call: ophalen van beschikbare questionnaires
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:
GET questionnaires requestGET questionnaires request.png787x261 7.89 KB
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.
Respondenten uitnodigen voor een vragenlijst
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.
Ophalen van alle benodigde velden
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.
Uitnodigingen aanmaken
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.
Reacties en resultaten ophalen
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"
}
}
