API voor bemiddelaars
Versie v1 · bijgewerkt 11 november 2026
Een bemiddelaar met een betaald account haalt met een eigen sleutel op wat het tabblad Kandidaten toont. Het meldt de stand terug en ontvangt berichten van ZZPdock. Alles gaat over de eigen opdrachten van het bureau en alleen over zzp'ers die zelf hebben aangezet dat bureaus hen mogen benaderen. De beschrijving in OpenAPI 3.1 staat op https://zzpdock.nl/api/v1/bemiddelaar/openapi.json.
Sleutel
- Je maakt een sleutel zelf aan op het scherm Koppelingen van je dashboard. Een sleutel begint met
zzpd_live_ofzzpd_test_. - Stuur hem mee als
Authorization: Bearer <sleutel>. Alleen via https. Een sleutel in het adres wordt geweigerd. - De sleutel staat één keer op het scherm. Vernieuwen maakt een opvolger en de oude werkt nog 24 uur. Intrekken werkt direct.
- Rechten per sleutel:
kandidaten:lezenencontact:lezenenstand:schrijven. - Elk antwoord draagt
ZZPdock-Verzoek-Id. Een antwoord met persoonsgegevens draagtCache-Control: no-store. - De rem: 300 verzoeken per minuut per bureau en 60 voor contact en cv samen. Elk antwoord draagt
RateLimit-LimitenRateLimit-RemainingenRateLimit-Reset. Een 429 draagtRetry-After. - ID's zijn tekst van hooguit 64 tekens:
opd_voor een opdracht enkand_voor een kandidaat. Eenkandidaat_idgeldt per bureau en is bij elke opdracht van jouw bureau gelijk. - Tijd is ISO 8601 in UTC (
2026-11-11T09:30:00Z). Een datum isJJJJ-MM-DD. Een tarief is een getal in euro per uur.
Lijsten
Elke lijst werkt hetzelfde en heeft dezelfde vorm.
{
"gegevens": [],
"volgende": null
}aantal: hoeveel per keer (standaard 50 en hoogstens 100).na: de cursor uit het vorige antwoord. Hij blijft 24 uur geldig.gewijzigd_sinds: een tijdstip. Je krijgt dan alleen wat sindsdien veranderde (oudste eerst) en ook de vervallen regels metvervallen: true. Zo houdt een wervingssysteem zijn kopie gelijk zonder alles opnieuw op te halen.- Een profiel opvragen telt voor de zzp'er als profielbezoek. Contactgegevens of een cv opvragen telt als contactmoment. De zzp'er ziet beide in Mijn overzicht.
- Het profiel draagt een
ETag. Stuur die terug alsIf-None-Match. Is het profiel gelijk dan krijg je 304 en telt dat niet als profielbezoek. - Een schrijvend verzoek mag
Idempotency-Keydragen (hooguit 100 tekens). Hetzelfde verzoek binnen 24 uur geeft het eerste antwoord terug.
Fouten
Elke fout heeft de passende HTTP-status en dezelfde vorm. De code is het contract en de melding mag veranderen.
{
"fout": {
"code": "geen_recht",
"melding": "Deze sleutel mag geen contactgegevens lezen.",
"veld": null,
"verzoek_id": "vrz_k2m8qz4c7w1x9d3f5h6j"
}
}400 ongeldige_invoer: Een veld klopt niet. Het antwoord noemt welk veld.400 cursor_verlopen: De cursor is ouder dan 24 uur. Begin opnieuw.401 sleutel_ontbreekt: Geen sleutel meegestuurd.401 sleutel_ongeldig: De sleutel is onbekend of ingetrokken.403 geen_recht: De sleutel mist het recht voor dit adres.403 abonnement_verlopen: Het bureau staat niet op betaald.403 onderdeel_uit: Het onderdeel staat voor dit bureau uit.404 niet_gevonden: Bestaat niet of is niet van dit bureau.404 geen_cv: Er is geen cv-bestand bewaard.409 idempotentie_conflict: Dezelfde Idempotency-Key met een andere inhoud.409 geen_contact: Stand gemeld zonder eerder contactmoment bij deze opdracht.410 niet_meer_beschikbaar: De kandidaat staat niet meer in de lijst.429 te_veel_verzoeken: De rem. De kop Retry-After zegt hoeveel seconden je wacht.500 interne_fout: Een fout bij ZZPdock.
Adressen
Alles staat onder https://zzpdock.nl/api/v1/bemiddelaar. De voorbeelden gebruiken de ID's van de testgegevens (zie Testen) en werken met een testsleutel.
GET /sleutel
Wie ben ik: bureau plus rechten plus soort sleutel. Zonder sleutel.
curl "https://zzpdock.nl/api/v1/bemiddelaar/sleutel"{
"bureau": "Voorbeeld Interim",
"sleutel_id": "sl_7h2k9m4p1q8r5t3v6w0x",
"soort": "test",
"rechten": [
"kandidaten:lezen",
"contact:lezen",
"stand:schrijven"
],
"toegang_tot": "2027-02-20T00:00:00Z"
}GET /opdrachten
Eigen opdrachten met het aantal passende kandidaten. Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"gegevens": [
{
"opdracht_id": "opd_test0000000000000001",
"titel": "Voorbeeldopdracht projectmanager",
"opdrachtgever": "Gemeente Voorbeeldstad",
"plaats": "Voorbeeldstad",
"uren_per_week": 32,
"startdatum": "2027-01-04",
"tarief_max": 100,
"status": "open",
"url": null,
"bron": "zzpdock",
"externe_referentie": null,
"geplaatst_op": "2026-10-20T08:00:00Z",
"gewijzigd_op": "2026-11-01T08:00:00Z",
"passende_kandidaten": 3
}
],
"volgende": null
}GET /opdrachten/{opdracht_id}
Eén opdracht. Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"opdracht_id": "opd_test0000000000000001",
"titel": "Voorbeeldopdracht projectmanager",
"opdrachtgever": "Gemeente Voorbeeldstad",
"plaats": "Voorbeeldstad",
"uren_per_week": 32,
"startdatum": "2027-01-04",
"tarief_max": 100,
"status": "open",
"url": null,
"bron": "zzpdock",
"externe_referentie": null,
"geplaatst_op": "2026-10-20T08:00:00Z",
"gewijzigd_op": "2026-11-01T08:00:00Z",
"passende_kandidaten": 3
}GET /opdrachten/{opdracht_id}/kandidaten
De kandidaten zoals op de kaart, beste eerst. Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"gegevens": [
{
"kandidaat_id": "kand_test0000000000000001",
"volgorde": 1,
"naam": "Anna Testpersoon",
"functie": "Projectmanager",
"tarief": 95,
"jaren_ervaring": 12,
"beschikbaar_vanaf": "2027-01-01",
"uren_per_week": 32,
"regio": [
"Voorbeeldstad"
],
"werkvorm": [
"hybride"
],
"past_bij_opdracht": {
"voldoet": 4,
"voldoet_niet": 0
},
"cv_beschikbaar": true,
"stand": "procedure",
"profiel_gewijzigd_op": "2026-10-28T09:00:00Z",
"passend_sinds": "2026-10-30T06:40:00Z",
"vervallen": false
}
],
"volgende": null
}GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}
Het profiel (telt als profielbezoek). Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"kandidaat_id": "kand_test0000000000000001",
"opdracht_id": "opd_test0000000000000001",
"naam": "Anna Testpersoon",
"functie": "Projectmanager",
"tarief": 95,
"jaren_ervaring": 12,
"beschikbaar_vanaf": "2027-01-01",
"uren_per_week": 32,
"regio": [
"Voorbeeldstad"
],
"werkvorm": [
"hybride"
],
"past_bij_opdracht": {
"voldoet": 4,
"voldoet_niet": 0,
"eisen": [
{
"eis": "Hbo werk- en denkniveau",
"voldoet": true
},
{
"eis": "Ervaring bij een overheidsorganisatie",
"voldoet": true
}
]
},
"werkervaring": [
{
"functie": "Projectmanager",
"opdrachtgever": "Voorbeeld Organisatie",
"van": "2022-01",
"tot": null,
"maanden": 46
}
],
"opleidingen": [
"Voorbeeldopleiding (hbo)"
],
"certificaten": [
"Voorbeeldcertificaat"
],
"vaardigheden": [
"Plannen",
"Samenwerken"
],
"talen": [
"Nederlands",
"Engels"
],
"cv_beschikbaar": true,
"stand": "procedure",
"profiel_gewijzigd_op": "2026-10-28T09:00:00Z"
}POST /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/contact
Mailadres plus telefoon (telt als contactmoment). Recht: contact:lezen.
curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/contact" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"kandidaat_id": "kand_test0000000000000001",
"naam": "Anna Testpersoon",
"mailadres": "anna@voorbeeld.nl",
"telefoon": "+31 6 00000001",
"eerste_contactmoment_op": "2026-11-02T09:00:00Z"
}GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/cv
Het cv-bestand (telt als contactmoment). Recht: contact:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/cv" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"GET /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/stand
De laatste stand plus de bevestiging. Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/stand" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"opdracht_id": "opd_test0000000000000001",
"kandidaat_id": "kand_test0000000000000001",
"stand": "procedure",
"startdatum": null,
"einddatum": null,
"reden": null,
"gemeld_op": "2026-11-02T10:00:00Z",
"bevestiging": "bevestigd",
"bevestigd_op": "2026-11-02T12:00:00Z"
}POST /opdrachten/{opdracht_id}/kandidaten/{kandidaat_id}/stand
Een stand melden. Recht: stand:schrijven.
curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/opdrachten/opd_test0000000000000001/kandidaten/kand_test0000000000000001/stand" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: stand-001" \
-d '{"stand":"aangenomen","startdatum":"2027-01-04","einddatum":"2027-07-02"}'{
"opdracht_id": "opd_test0000000000000001",
"kandidaat_id": "kand_test0000000000000001",
"stand": "aangenomen",
"startdatum": "2027-01-04",
"einddatum": "2027-07-02",
"reden": null,
"gemeld_op": "2026-11-20T10:02:00Z",
"bevestiging": "open",
"bevestigd_op": null
}POST /kandidaten/{kandidaat_id}/gewist
Melden dat de gegevens gewist zijn. Recht: stand:schrijven.
curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/kandidaten/kand_test0000000000000001/gewist" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"kandidaat_id": "kand_test0000000000000001",
"gewist_gemeld_op": "2026-11-12T08:00:00Z"
}GET /gebeurtenissen
Alle berichten van de laatste 30 dagen (ook zonder berichtenadres). Recht: kandidaten:lezen.
curl "https://zzpdock.nl/api/v1/bemiddelaar/gebeurtenissen" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>"{
"gegevens": [
{
"gebeurtenis_id": "evt_1q2w3e4r5t6y7u8i9o0p",
"soort": "stand.bevestigd",
"aangemaakt_op": "2026-11-21T09:00:00Z",
"api_versie": "v1",
"test": true,
"gegevens": {
"opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
"kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p",
"stand": "aangenomen"
}
}
],
"volgende": null
}POST /test/gebeurtenis
Laat ZZPdock een voorbeeldbericht sturen (alleen testsleutel). Alleen met een testsleutel.
curl -X POST "https://zzpdock.nl/api/v1/bemiddelaar/test/gebeurtenis" \
-H "Authorization: Bearer zzpd_test_<jouw testsleutel>" \
-H "Content-Type: application/json" \
-d '{"soort":"stand.bevestigd"}'{
"gebeurtenis_id": "evt_1q2w3e4r5t6y7u8i9o0p",
"soort": "stand.bevestigd",
"aangemaakt_op": "2026-11-21T09:00:00Z",
"api_versie": "v1",
"test": true,
"gegevens": {
"opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
"kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p",
"stand": "aangenomen"
}
}GET /openapi.json
De machineleesbare beschrijving. Zonder sleutel.
curl "https://zzpdock.nl/api/v1/bemiddelaar/openapi.json"Berichten
ZZPdock stuurt een bericht naar het adres dat je op het scherm Koppelingen neerzet. Een bericht bevat alleen ID's en nooit persoonsgegevens: je haalt de inhoud op met je sleutel. Ontbreekt het adres dan staan dezelfde berichten 30 dagen in GET /gebeurtenissen.
kandidaat.passend: Een zzp'er staat voor het eerst in de lijst van een opdracht.stand.bevestigd: De zzp'er bevestigt een gemelde stand.stand.tegengesproken: De zzp'er spreekt een gemelde stand tegen.kandidaat.wissen: Je moet de gegevens van deze kandidaat wissen. Er staat nooit een reden bij.test.ping: De testknop op het scherm Koppelingen of POST /test/gebeurtenis.
{
"gebeurtenis_id": "evt_3n5b7v9c1x2z4l6k8j0h",
"soort": "kandidaat.passend",
"aangemaakt_op": "2026-11-11T06:40:12Z",
"api_versie": "v1",
"test": false,
"gegevens": {
"opdracht_id": "opd_4f8k2m9q1w7x3c5v6b0n",
"kandidaat_id": "kand_9q2w4e6r8t1y3u5i7o0p"
}
}- Alleen https. Een adres dat naar een intern of lokaal netwerk wijst wordt geweigerd. ZZPdock volgt geen doorverwijzingen en wacht 5 seconden.
- Elk antwoord 2xx telt als aangekomen. Al het andere wordt herhaald na 1 minuut en 5 minuten en 30 minuten en 2 uur en 6 uur en 12 uur en 24 uur. Daarna staat het bericht op mislukt. Je stuurt het vanaf het scherm opnieuw.
- De volgorde is niet gegarandeerd en een bericht kan twee keer komen. Herken dubbelen aan
gebeurtenis_id. Sla een onbekend soort bericht over zonder te stoppen. kandidaat.wissenstaat altijd aan. Ingegevensstaan hetkandidaat_idenwissen_voor(een datum zeven dagen later). Meld daarna metPOST /kandidaten/{kandidaat_id}/gewistdat je gewist hebt.
Handtekening controleren
Elk bericht draagt ZZPdock-Handtekening: t=<tijd>,v1=<hmac>. De hmac is HMAC-SHA256 over <tijd>.<inhoud> met het geheim van je adres (whsec_ plus 43 tekens). Gebruik de ruwe inhoud zoals die binnenkomt. Weiger een bericht dat ouder is dan 5 minuten. Na het vernieuwen van het geheim staan er 24 uur twee v1-waarden onder het bericht: elk geheim mag kloppen.
Een voorbeeld dat je kunt narekenen met geheim whsec_VoorbeeldGeheimVoorbeeldGeheimVoorbeeld1234 en tijd 1794303612:
ZZPdock-Handtekening: t=1794303612,v1=fd879adc3b8d457f8b4901ba067554511d34c93ec2cb70fcf3f60fb93c194642
{"gebeurtenis_id":"evt_3n5b7v9c1x2z4l6k8j0h","soort":"kandidaat.passend","aangemaakt_op":"2026-11-11T06:40:12Z","api_versie":"v1","test":false,"gegevens":{"opdracht_id":"opd_4f8k2m9q1w7x3c5v6b0n","kandidaat_id":"kand_9q2w4e6r8t1y3u5i7o0p"}}Node
import { createHmac, timingSafeEqual } from "node:crypto"
// kop: de waarde van ZZPdock-Handtekening, inhoud: de ruwe body (niet opnieuw geserialiseerd)
export function controleer(kop, inhoud, geheim, nu = Date.now() / 1000) {
const delen = kop.split(",")
const tijd = Number(delen.find((d) => d.startsWith("t="))?.slice(2))
const waarden = delen.filter((d) => d.startsWith("v1=")).map((d) => d.slice(3))
if (!Number.isFinite(tijd) || Math.abs(nu - tijd) > 300) return false
const verwacht = createHmac("sha256", geheim).update(`${tijd}.${inhoud}`).digest()
return waarden.some((w) => {
const b = Buffer.from(w, "hex")
return b.length === verwacht.length && timingSafeEqual(b, verwacht)
})
}Python
import hashlib, hmac, time
def controleer(kop, inhoud, geheim, nu=None):
# kop: de waarde van ZZPdock-Handtekening, inhoud: de ruwe body (bytes)
nu = nu or time.time()
delen = kop.split(",")
tijd = next((int(d[2:]) for d in delen if d.startswith("t=")), None)
waarden = [d[3:] for d in delen if d.startswith("v1=")]
if tijd is None or abs(nu - tijd) > 300:
return False
verwacht = hmac.new(geheim.encode(), f"{tijd}.".encode() + inhoud, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(w, verwacht) for w in waarden)Testen
- Een testsleutel (
zzpd_test_) werkt op dezelfde adressen met dezelfde vormen. Alle gegevens zijn verzonnen en vast: drie opdrachten met zes kandidaten. De mailadressen eindigen opvoorbeeld.nl. - Een testsleutel raakt geen gegevens van echte zzp'ers. Er ontstaat geen profielbezoek en geen contactmoment. Een gemelde stand wordt getoetst en teruggegeven maar niet bewaard.
- Elke testkandidaat heeft al een contactmoment behalve de zesde bij de derde opdracht. Daarmee test je
409 geen_contact. POST /test/gebeurtenismet{ "soort": "stand.bevestigd" }laat ZZPdock dat bericht met"test": truenaar je adres sturen.- Een testsleutel werkt ook als de betaling gestopt is. De rem en het foutformaat zijn gelijk aan die van een echte sleutel.
Wijzigingen
- Binnen v1 verdwijnt een veld nooit en verandert het nooit van naam of type of betekenis. Elk veld staat altijd in het antwoord (onbekend is
nullen een lege lijst is[]). - Wat wel mag binnen v1: een nieuw veld in een antwoord en een nieuw adres en een nieuw soort bericht en een nieuwe waarde in een keuzelijst en een nieuw recht voor een sleutel. Sla onbekende velden en waarden over.
- Alles daarbuiten komt in
/api/v2/bemiddelaar. Beide versies draaien dan minstens twaalf maanden naast elkaar en een aflopende versie draagt de kopSunsetmet de einddatum. - 11 november 2026: v1 met sleutels en opdrachten en kandidaten en profiel en contact en cv en stand en wissen en berichten en de testsleutel.