Documentatie
De API van Referentiecheck
Je ATS start de check, de kandidaat en de referenten doen hun werk bij ons, en je systeem haalt het rapport op. Vier endpoints, geen SDK nodig.
Aan de slag
Basis-url en sleutel
Alles staat onder https://www.referentiecheck.app/api/v1. Een beheerder maakt een sleutel aan onder Instellingen, API. Je ziet hem één keer. Stuur hem mee als bearer token; zet hem nooit in een url, want adressen belanden in logbestanden. Doe je dat toch, dan antwoorden we met key_in_url.
curl https://www.referentiecheck.app/api/v1/templates \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL"Een sleutel begint met rc_live_. De koppeling zit in Bureau en Groep; op Team is het een add-on. Zonder dat plan antwoorden we met plan_required.
Rechten
Drie scopes, niet meer dan nodig
Je kiest de rechten bij het aanmaken. Een sleutel zonder het juiste recht krijgt 403 met missing_scope.
De rechten
| Veld | Type | Wat het doet |
|---|---|---|
| checks:write | schrijven | Een check starten. |
| checks:read | lezen | De status van een check opvragen en de vragenlijsten ophalen. |
| reports:read | lezen | Het rapport ophalen, inclusief de link naar het volledige rapport. |
Spelregels
Limieten, herhalingen en fouten
Limiet
60 verzoeken per minuut en 600 per uur, per sleutel. Daarboven 429 met Retry-After.
Idempotentie
Stuur bij POST een Idempotency-Key mee. Herhaal je hetzelfde verzoek binnen 24 uur, dan krijg je hetzelfde antwoord en geen tweede check.
Fouten
Altijd dezelfde vorm. Programmeer op code, toon melding aan de mens die het logboek leest.
{
"error": {
"code": "missing_scope",
"melding": "Deze sleutel heeft de rechten \"reports:read\" niet."
}
}Foutcodes
| Veld | Type | Wat het doet |
|---|---|---|
| invalid_request | 400 | Een veld ontbreekt of klopt niet. Het antwoord noemt het veld. |
| key_in_url | 400 | Je zette een sleutel in de querystring. Gebruik de header. |
| invalid_key | 401 | Onbekende of ingetrokken sleutel. |
| missing_scope | 403 | De sleutel mist het recht voor dit endpoint. |
| plan_required | 403 | De koppeling zit niet in dit abonnement. |
| not_found | 404 | Bestaat niet, of hoort bij een andere werkruimte. |
| duplicate_external_ref | 409 | Voor deze external_ref loopt al een check. |
| idempotency_conflict | 409 | Dezelfde Idempotency-Key met een andere body. |
| idempotency_in_progress | 409 | Het eerste verzoek loopt nog. Probeer het zo opnieuw. |
| report_not_ready | 409 | Er is nog geen rapport. De status staat erbij. |
| no_valid_mandate | 422 | De betaling is niet rond, dus er start geen nieuwe check. |
| rate_limited | 429 | Te veel verzoeken. Wacht zoals Retry-After aangeeft. |
| server_error | 500 | Onze fout. Probeer het opnieuw. |
POST /v1/checks
Een check starten
Vereist het recht checks:write
Dit maakt de check aan en mailt de kandidaat de uitnodiging. Hij geeft toestemming, vult zijn referenten in en die krijgen de vragenlijst. Wil je de mail zelf sturen, zet dan send_invite op false en gebruik de candidate_link uit het antwoord.
curl https://www.referentiecheck.app/api/v1/checks \
-X POST \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: sollicitatie-8412" \
-d '{
"candidate": {
"name": "Sanne de Vries",
"email": "sanne@voorbeeld.nl",
"external_ref": "kandidaat-2291"
},
"job_title": "Accountmanager",
"role_type": "sales",
"min_referees": 2,
"deadline": "2026-09-30",
"external_ref": "sollicitatie-8412"
}'Invoer
| Veld | Type | Wat het doet |
|---|---|---|
| candidate.name | tekst, verplicht | Naam van de kandidaat, 2 tot 120 tekens. |
| candidate.email | tekst | Zonder adres kunnen wij de uitnodiging niet sturen. |
| candidate.phone | tekst | Optioneel, alleen voor de recruiter. |
| candidate.external_ref | tekst | Jouw id van de kandidaat. Wij koppelen daarop terug. |
| job_title | tekst, verplicht | De functie waarop hij solliciteert. |
| template_id | uuid | Een vragenlijst uit GET /v1/templates. |
| role_type | tekst | universeel, sales, developer of manager. Alternatief voor template_id. |
| min_referees | getal | 2 tot 5. Standaard 2. Zoveel referenten moeten invullen. |
| deadline | datum | jjjj-mm-dd. Standaard over 14 dagen, maximaal 3 maanden vooruit. |
| external_ref | tekst | Jouw id van de aanvraag. Uniek per werkruimte. |
| send_invite | booleaans | Standaard true. False houdt de check als concept klaar. |
Antwoord 201:
{
"id": "6f0e2b6c-0f5b-4c7a-9a1f-2b4d8e9c1a77",
"status": "pending_candidate",
"external_ref": "sollicitatie-8412",
"job_title": "Accountmanager",
"deadline": "2026-09-30T23:59:59.000Z",
"min_referees": 2,
"candidate": { "id": "1c9...", "name": "Sanne de Vries", "external_ref": "kandidaat-2291" },
"candidate_link": "https://www.referentiecheck.app/k/6a2f...",
"expires_at": "2026-10-07T23:59:59.000Z",
"invited": true
}Lukt de mail niet, dan blijft de check staan als concept, is invited false en staat de reden in warning. De kandidaatlink werkt dan gewoon.
GET /v1/checks
De lijst met checks
Vereist het recht checks:read
Nieuwste eerst. Zoek je één check terug op je eigen referentie, filter dan op external_ref.
curl "https://www.referentiecheck.app/api/v1/checks?status=collecting&limit=25" \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL"Filters
| Veld | Type | Wat het doet |
|---|---|---|
| status | tekst | Eén status, of meerdere gescheiden door een komma. |
| external_ref | tekst | Jouw id van de aanvraag. |
| created_after | datum | Alleen checks vanaf deze datum. |
| limit | getal | 1 tot 100. Standaard 25. |
| cursor | tekst | De next_cursor uit het vorige antwoord. |
{
"data": [
{
"id": "6f0e2b6c-...",
"status": "collecting",
"external_ref": "sollicitatie-8412",
"job_title": "Accountmanager",
"deadline": "2026-09-30T23:59:59.000Z",
"min_referees": 2,
"candidate": { "id": "1c9...", "name": "Sanne de Vries", "external_ref": "kandidaat-2291" },
"referees": { "total": 3, "completed": 2, "declined": 0 },
"report_ready": false,
"created_at": "2026-09-16T09:12:03.412Z",
"updated_at": "2026-09-18T14:41:55.882Z"
}
],
"next_cursor": null
}Statussen
| Veld | Type | Wat het doet |
|---|---|---|
| draft | concept | Aangemaakt, de kandidaat weet nog van niets. |
| pending_candidate | wacht | De kandidaat moet toestemming geven en referenten opgeven. |
| collecting | loopt | De referenten zijn aan zet. |
| completed | klaar | Het minimum is gehaald, het rapport staat klaar. |
| expired | verlopen | De deadline is voorbij zonder genoeg antwoorden. |
| cancelled | gestopt | Geannuleerd. Alle openstaande links zijn vervallen. |
GET /v1/checks/{id}
De stand van één check
Vereist het recht checks:read
Hiermee vul je je eigen scherm: wie er is uitgenodigd, wie heeft ingevuld en hoeveel herinneringen er zijn gestuurd. De e-mailadressen van de referenten en hun antwoorden krijg je niet.
curl https://www.referentiecheck.app/api/v1/checks/6f0e2b6c-0f5b-4c7a-9a1f-2b4d8e9c1a77 \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL"{
"id": "6f0e2b6c-...",
"status": "collecting",
"external_ref": "sollicitatie-8412",
"consent_given_at": "2026-09-16T10:02:44.120Z",
"deadline": "2026-09-30T23:59:59.000Z",
"min_referees": 2,
"candidate": { "id": "1c9...", "name": "Sanne de Vries", "external_ref": "kandidaat-2291" },
"referees": [
{
"id": "b31...",
"name": "Mark Jansen",
"relation": "voormalig leidinggevende",
"company": "Vertex BV",
"status": "completed",
"invited_at": "2026-09-16T10:05:01.004Z",
"submitted_at": "2026-09-17T08:22:19.774Z",
"reminders_sent": 1
}
],
"progress": { "completed": 2, "minimum": 2, "total": 3, "declined": 0, "label": "2 van 2" },
"report": { "ready": true, "generated_at": "2026-09-18T14:41:55.882Z" }
}Een check van een andere werkruimte geeft 404, nooit 403. Een 403 zou bevestigen dat de id bestaat.
GET /v1/checks/{id}/rapport
Het rapport
Vereist het recht reports:read
Scores, samenvatting, verschillen tussen referenten, integriteitssignalen en een link naar het volledige rapport. De letterlijke antwoorden van de referenten zitten er niet in: die blijven hier staan, achter een link die verloopt en in te trekken is. Zo verhuist de persoonsdata niet mee naar jouw systeem.
curl https://www.referentiecheck.app/api/v1/checks/6f0e2b6c-0f5b-4c7a-9a1f-2b4d8e9c1a77/rapport \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL"{
"check_id": "6f0e2b6c-...",
"external_ref": "sollicitatie-8412",
"status": "completed",
"summary": "Drie referenten bevestigen hetzelfde beeld ...",
"recommendation": "positief",
"scores": {
"overall": "positief",
"confirmed": ["Haalt afspraken na"],
"discuss": ["Werkdruk in piekweken"],
"follow_up_questions": ["Hoe stuurde zij bij toen de targets niet gehaald werden?"],
"consistency": { "aantal": 4, "totaal": 5 },
"competencies": [
{
"key": "betrouwbaarheid",
"label": "Betrouwbaarheid",
"average": 8.3,
"low": 8,
"high": 9,
"count": 3,
"agreement": "hoog",
"difference": false
}
],
"grade": { "average": 8.2, "count": 3 },
"rehire": { "yes": 3, "total": 3 },
"incomplete": null
},
"differences": [
{
"competency": "omgaan_met_druk",
"label": "Omgaan met druk",
"description": "Twee referenten geven een 8, een derde een 5.",
"referees": [{ "referee_id": "b31...", "name": "Mark Jansen", "value": 8 }]
}
],
"integrity_signals": {
"count": 1,
"advice": "Bel de tweede referent even na.",
"referees": [
{
"referee_id": "c77...",
"name": "Ilse Bakker",
"relation": "collega",
"signals": [
{ "code": "netwerk_gedeeld", "severity": "oranje", "explanation": "Twee referenten vulden in vanaf hetzelfde netwerk." }
]
}
]
},
"received": { "completed": 3, "minimum": 2, "total": 3, "label": "3 van 2" },
"report_url": "https://www.referentiecheck.app/rapport/9d1c...",
"report_url_expires_at": "2026-10-18T14:41:55.882Z",
"report_url_revoked": false,
"generated_at": "2026-09-18T14:41:55.882Z"
}De link wordt bij het eerste ophalen aangemaakt en is dertig dagen geldig. Heeft een collega de deellink ingetrokken, dan blijft dat zo: report_url is dan null en report_url_revoked true. Is er nog geen rapport, dan krijg je 409 met report_not_ready en de huidige status.
GET /v1/templates
De vragenlijsten
Vereist het recht checks:read
Voor het keuzemenu in je eigen scherm. Elke werkruimte heeft de vier standaardlijsten en eventueel eigen lijsten. De vragen zelf staan er niet in; die horen bij de referent.
curl https://www.referentiecheck.app/api/v1/templates \
-H "Authorization: Bearer $REFERENTIECHECK_SLEUTEL"{
"data": [
{
"id": "8b2...",
"name": "Sales",
"role_type": "sales",
"language": "nl",
"is_default": true,
"owner": "standaard",
"question_count": 8,
"score_count": 5,
"updated_at": "2026-09-02T11:00:00.000Z"
}
]
}Grenzen
Wat de API niet doet
- Geen ruwe antwoorden van referenten. Die lees je in het rapport, achter de link.
- Geen referenten toevoegen of vervangen. Dat doet de kandidaat, anders is de toestemming niets waard.
- Geen vragenlijsten bewerken. Dat gebeurt in de app.
- Geen wachten op een rapport. Zet een webhook op onder Instellingen, dan hoef je niet te pollen.
Een sleutel nodig?
Een beheerder maakt hem aan onder Instellingen, API. Loop je vast, mail dan hallo@referentiecheck.app met de naam van je sleutel, nooit de sleutel zelf.