Toggle sidebar

Participants-endpoints

Met de Participants-endpoints haal je deelnemers op (inclusief hun antwoorden, tags en uitnodiging-status), nodig je nieuwe deelnemers uit voor een privé-vragenlijst, of verwijder je een deelnemer.

Endpoints

Methode Pad Beschrijving
GET /api/v1/participants Alle deelnemers van je hele account
GET /api/v1/participants/{id} Details van één deelnemer
DELETE /api/v1/participants/{id} Een deelnemer verwijderen
GET /api/v1/participants/{id}/pdf PDF met de antwoorden van een deelnemer
GET /api/v1/surveys/{survey}/participants Deelnemers van één specifieke vragenlijst
GET /api/v1/surveys/{survey}/participants/{id} Eén deelnemer binnen een vragenlijst
POST /api/v1/surveys/{survey}/participants Nieuwe deelnemer toevoegen aan een privé-vragenlijst

Een deelnemer toevoegen (privé-vragenlijst)

Hiermee maak je een nieuwe deelnemer aan en stuur je standaard direct een uitnodigingsmail.

POST /api/v1/surveys/123/participants
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

{
  "email": "deelnemer@voorbeeld.nl",
  "send_mail": true,
  "tags": {
    "first_name": "Jan",
    "department": "Marketing"
  }
}

Velden

Veld Verplicht Beschrijving
email ja E-mailadres van de deelnemer. Wordt gevalideerd op formaat, op blacklist en op de uitnodigingslimiet uit de vragenlijst-instellingen
send_mail nee true (standaard) verstuurt direct een uitnodigingsmail; false maakt alleen de deelnemer aan
tags nee Object met tag-key → waarde. Tag-keys vind je via de vraagstructuur (de keys zijn die uit de tags-zijbalk in de vragenlijst)

Verplichte tags die in de vragenlijst zijn gedefinieerd, moeten ook hier ingevuld worden.

Werkt alleen voor privé-vragenlijsten

Het toevoegen van deelnemers via de API werkt alleen voor privé-vragenlijsten. Bij een openbare vragenlijst krijg je een 400 Bad Request met de melding "Can not invite participants to a public survey".

Lijst opvragen

GET /api/v1/surveys/123/participants?include=answers.question,tags.tag
Authorization: Bearer <token>
Accept: application/json

Includes

Naam Wat krijg je erbij
answers.question Alle antwoorden, met bij elk antwoord de bijbehorende vraag
tags.tag Alle tags van de deelnemer met de tag-definitie
answers.media Eventuele bestanden bij bestand-vragen

Response-velden

Per deelnemer krijg je:

  • id - uniek ID
  • email - e-mailadres
  • token - unieke token (voor de persoonlijke vragenlijst-URL)
  • invited_at - datum/tijd van uitnodiging
  • responded_at - datum/tijd van voltooiing (of null als nog niet gereageerd)
  • tags - array met tag-waarden (alleen als include)
  • answers - array met antwoorden (alleen als include)
  • reminder - info over verstuurde herinneringen (alleen als include)
  • signature - handtekening-data (alleen als include)

Een deelnemer verwijderen

DELETE /api/v1/participants/789
Authorization: Bearer <token>

Geeft "204 No Content" bij succes. Antwoorden van de deelnemer worden ook verwijderd en zijn niet terug te halen.

PDF van antwoorden ophalen

GET /api/v1/participants/789/pdf
Authorization: Bearer <token>

Geeft een PDF-bestand terug met de gegeven antwoorden. Handig om individuele rapportages te genereren.

Gebruikssituaties

  • CRM-koppeling: synchroniseer nieuwe leads of klanten automatisch als deelnemers naar een onboarding-vragenlijst.
  • Antwoorden synchroniseren: haal periodiek nieuwe responded_at op om antwoorden naar je eigen database te kopiëren.
  • PDF-archief: download per deelnemer een PDF voor archief- of compliance-doeleinden.

Veelgestelde vragen

Het tags-object gebruikt de key van een tag (zoals zichtbaar in de tags-zijbalk van de vragenlijst), niet het label. De key is meestal een korte naam zoals first_name of department.

De call mislukt met een validatie-fout. Dat is bewust - om te voorkomen dat afgemelde adressen toch nog uitnodigingen ontvangen.

Lijst-endpoints gebruiken cursor-paginatie via lazyById. Volg de next link in de response om de volgende batch op te halen. Itereren totdat er geen next-link meer is.

Op dit moment niet - alleen aanmaken, ophalen en verwijderen. Wil je een tag bijwerken? Verwijder de deelnemer en maak hem opnieuw aan met de juiste tag-waarden.
Surveys
Users