De Will Werk API

Koppel je eigen systeem aan Will Werk. Je plaatst en beheert hiermee je vacatures, haalt de kandidaten op die Will heeft gesproken, vraagt een cv op, en schrijft de status van een kandidaat terug. Werkt met elk systeem dat een REST-koppeling aankan, bijvoorbeeld Recruitee.

Beginnen

Maak een sleutel aan in je portaal onder Mijn account, kaart API-koppeling. Je ziet hem daar één keer; wij bewaren alleen een versleutelde afdruk, dus bij verlies maak je een nieuwe aan. API-toegang hoort bij de pakketten Pro en Enterprise.

Stuur de sleutel mee in de Authorization-kop:

curl https://www.willwerk.nl/api/v1/mij \
  -H "Authorization: Bearer ww_jouw_sleutel"

Werkt dat, dan krijg je je bedrijfsnaam terug en weet je meteen wat de sleutel mag:

{
  "bedrijf": "Voorbeeld BV",
  "pakket": "Pro",
  "sleutel": "Recruitee",
  "mag_schrijven": false,
  "limiet_per_uur": 1000
}

Vacatures ophalen

curl "https://www.willwerk.nl/api/v1/vacatures?limit=25" \
  -H "Authorization: Bearer ww_jouw_sleutel"

{
  "vacatures": [
    {
      "id": 3289,
      "titel": "Word Mechanisch Werkvoorbereider",
      "categorie": "Techniek",
      "locatie": "Ouderkerk aan den IJssel",
      "type": "Vast",
      "salaris": "Conform cao Metaal en Techniek",
      "slug": "word-mechanisch-werkvoorbereider-ouderkerk",
      "actief": true,
      "datum_toegevoegd": "2026-07-02T09:14:00+00:00"
    }
  ],
  "totaal": 42, "limit": 25, "offset": 0
}

Een vacature plaatsen

Hiervoor heb je een sleutel nodig die mag schrijven. Wat je stuurt komt op onze site, gaat via de feed naar de jobboards en wordt door Will voorgelezen aan kandidaten, dus het gaat eerst door dezelfde controle als alles wat wij zelf plaatsen.

curl -X POST https://www.willwerk.nl/api/v1/vacatures \
  -H "Authorization: Bearer ww_jouw_sleutel" \
  -H "Content-Type: application/json" \
  -d '{
    "titel": "Senior Java Developer (m/v)",
    "categorie": "IT & Technologie",
    "locatie": "Utrecht",
    "type": "Vast",
    "salaris": "€ 4.500 tot € 6.000 per maand",
    "bron_url": "https://jouwsite.nl/vacature/java-1",
    "beschrijving": "... Functie-eisen: ... Arbeidsvoorwaarden: ... Interesse? ..."
  }'

{
  "ok": true,
  "id": 3764,
  "titel": "Word Senior Java Developer",
  "url": "https://www.willwerk.nl/vacature/word-senior-java-developer-utrecht",
  "waarschuwingen": [],
  "titel_aangepast": "Onze vacatures beginnen met 'Word'. Jouw titel is geplaatst als: …"
}

Wat tegenhoudt en wat niet

Een ontbrekende of ongeldige categorie, een ongeldig type, een te korte beschrijving en placeholdertekst ("recruiter vult dit later aan") leveren een 422 op met een lijst onder problemen. Er wordt dan niets geplaatst.

De rest komt terug onder waarschuwingen en houdt niets tegen. De belangrijkste is het salaris: geef je geen bedrag op, dan publiceren wij het mediaanloon uit de CBS-cijfers als indicatie, met de vermelding dat het niet jouw aanbod is. Dat doen we omdat jobboards vacatures zonder bedrag weigeren. Een eigen bedrag werkt beter, en vanaf 1 januari 2027 moet een kandidaat het sowieso weten voor het eerste gesprek.

Een vacature bijwerken of sluiten

Stuur alleen de velden die veranderen; de rest blijft staan. Dezelfde controle geldt, dus je kunt een vacature niet met een wijziging alsnog onder de eisen door krijgen.

curl -X PATCH https://www.willwerk.nl/api/v1/vacatures/3764 \
  -H "Authorization: Bearer ww_jouw_sleutel" \
  -H "Content-Type: application/json" \
  -d '{"actief": false}'

Een vacature verwijderen kan niet, en dat is met opzet: kandidaten die er al op hebben gereageerd horen bij die vacature. "actief": false haalt hem van de site.

Kandidaten ophalen

Je krijgt elke kandidaat die Will voor jouw vacatures heeft gesproken, net als in je portaal: ook als hij volgens Wills observatie niet aansluit, want jij beslist. Wie het gesprek nog niet heeft gehad zit er niet bij. Nieuwste eerst.

{
  "kandidaten": [
    {
      "id": 118,
      "voornaam": "Sanne", "achternaam": "de Vries",
      "email": "sanne@voorbeeld.nl", "telefoon": "+31 6 12345678",
      "woonplaats": "Rotterdam",
      "vacature": "Word Elektricien in Rotterdam",
      "status": "gesprek_gedaan",
      "via_match": false,
      "observatie": { "code": "sluit_aan", "tekst": "sluit aan op de functie-eisen" },
      "bevindingen": "Sanne werkt vijf jaar als installatiemonteur ...",
      "functie_eisen": [
        { "eis": "MBO niveau 3 elektrotechniek", "voldoet": "ja", "toelichting": "Diploma 2019" },
        { "eis": "Rijbewijs B", "voldoet": "onbekend", "toelichting": "" }
      ],
      "voorstelprofiel": "VOORSTELPROFIEL\nNaam: Sanne\nWoonplaats: Rotterdam\n...",
      "datum_toegevoegd": "2026-08-14T09:40:00+00:00",
      "datum_aangedragen": null,
      "heeft_cv": true
    }
  ],
  "totaal": 1, "limit": 100, "offset": 0
}

Eén kandidaat ophalen

Dezelfde velden als hierboven, altijd met het voorstelprofiel. Bestaat het nog niet, dan maakt Will het op dat moment; die aanroep duurt dan een paar seconden langer.

Een cv opvragen

Je krijgt geen bestand maar een ondertekende link die een uur geldig is. Download hem binnen dat uur; daarna vraag je gewoon een nieuwe op.

{ "url": "https://www.willwerk.nl/cvs/1786384327_cv.pdf?t=1787136000&s=a1b2…",
  "geldig_uren": 1 }

Een status terugschrijven

Heb je een kandidaat gesproken of een gesprek gepland, dan kun je dat hier doorgeven. Hiervoor heb je een sleutel nodig die mag schrijven; dat vink je aan bij het aanmaken.

curl -X PATCH https://www.willwerk.nl/api/v1/kandidaten/118 \
  -H "Authorization: Bearer ww_jouw_sleutel" \
  -H "Content-Type: application/json" \
  -d '{"status": "gesprek_klant"}'

Toegestaan is gesprek_klant (je hebt hem gesproken of een gesprek gepland). Of je iemand daarna aanneemt of afwijst houden wij niet bij; dat blijft bij jou. Dit werkt bij kandidaten die op gesprek_gedaan, aangedragen of gesprek_klant staan.

Foutmeldingen

Elke fout komt terug als {"error": "uitleg in gewone taal"}.

Verkeerslimiet

Duizend aanvragen per uur per sleutel. Dat is ruim voor een koppeling die elke paar minuten kijkt of er iets nieuws is. Kom je eraan, haal dan meer per keer op met limit in plaats van vaker te vragen.

Wat je met de gegevens mag doen

Zolang wij kandidaatgegevens voor je bewaren, doen wij dat als jouw verwerker. Haal je ze via deze API op en zet je ze in je eigen systeem, dan ben je voor die kopie zelf verwerkingsverantwoordelijke. Dat is geen formaliteit: vanaf dat moment ga jij over de bewaartermijn, de beveiliging, en de vragen die een kandidaat over die gegevens stelt.

De volledige afspraak staat in paragraaf 3.11 en 3.12 van de algemene voorwaarden. Kort samengevat:

• alleen gebruiken voor je eigen werving via Will Werk;
• niet doorverkopen, niet delen buiten je eigen dienstverleners, geen modellen mee trainen;
• zelf een bewaartermijn hanteren en die ook daadwerkelijk uitvoeren;
• verwijderen wij een kandidaat, dan verdwijnt hij niet uit jouw systeem. Dat moet je zelf doen; wij kunnen er niet bij.

Je sleutel is een wachtwoord. Zet hem in een omgevingsvariabele of een kluis, niet in code die je deelt. Vermoed je dat iemand anders hem heeft, trek hem dan meteen in in je portaal.

Vragen

Loop je vast, mail will@willwerk.nl met de aanvraag die misgaat en de foutmelding die je terugkreeg. Zet je sleutel er niet bij.