API documentatie

Algemeen

Introductie

Hier vind je alle documentatie die je nodig hebt om te integreren met de API van Werkzoeken.nl. Onze API is een REST-API en alle requests en responses zijn volledig in JSON. Mocht je op enig moment extra informatie willen of ondersteuning bij de integratie wensen, neem dan contact met ons op.

Rate limits

We hanteren onderstaande rate limits. Mocht je een uitzondering hierop willen dan kun je hiervoor contact met ons opnemen.
  • 200 requests per 60 seconden per account
  • 1000 requests per 60 seconden per IP-adres

Paginatie

De API van Werkzoeken.nl heeft een limiet aan items die per request van een lijst opgehaald kunnen worden. De limiet staat vast op 50 items. Wanneer je een lijst met items ophaalt heb je in het resultaat een item "rel" waarin wanneer nodig een "prev" en/of "next" item inzitten. Deze bevatten een URL die je kunt gebruiken om de volgende of vorige pagina op te halen. Al je parameters worden automatisch meegenomen. 
{
    "count": "int",
    "offset": "int",
    "limit": "int",
    "rel": {
        "prev": "string",
        "next": "string"
    }
}

HTTP-statuscodes

Met elke request geeft onze API een HTTP-statuscode terug om aan te geven of de request succesvol is of niet. Onderstaand vind je een overzicht van statuscodes die wij hanteren.
HTTP-statuscode Beschrijving
200 OK Request succesvol.
201 Created Item is succesvol toegevoegd.
204 No Content Item is succesvol verwijderd.
400 Bad Request De request is niet succesvol door ongeldige data.
401 Unauthorized Ongeldige autorisatie / apikey.
403 Forbidden Je hebt geen toegang tot dit endpoint.
404 Not Found Het gebruikte endpoint bestaat niet.
429 Too Many Requests Het maximaal aantal requests is bereikt (rate limit).
500 Internal Server Error Algemene fout, neem contact op met Werkzoeken.nl.

Foutmeldingen

Bij iedere request op de API kun je verschillende foutmeldingen terug krijgen. Dit kunnen bijvoorbeeld foutmeldingen zijn dat de parameters onjuist zijn, of bij het aanmaken van items dat de data niet valide is. Hieronder vind je de manier hoe wij deze foutmeldingen terugsturen. 
{
    "errors": [
        {
            "error": "string",
            "label": "string",
            "path": "string"
        }
    ]
}

Authenticatie

Credentials

Om gebruik te kunnen maken van de API van Werkzoeken.nl moet je eerst een API key aanmaken via je account. Log in op je account, ga vervolgens naar Instellingen > API om deze aan te maken. Bij het aanmaken van je API key kun je aangeven tot welke endpoints je toegang wil hebben.

API key

Elke request dient geauthenticeerd te worden. Dit kan door middel van een API key die als Bearer aan de header van iedere request moet worden toegevoegd.
Header
Authorization: Bearer <apikey>

Partner key

Gebruik je de API voor je klanten (bv. voor multiposting) dan dien je je extra te authenticeren zodat we weten welke partner je bent. Dit is een additionele header en zal naast de andere authenticatie header toegevoegd moeten worden. Hiermee kunnen wij in het account tonen wie de request heeft uitgevoerd voor het account. Neem contact met ons om een partner key aan te vragen.
Header
Partner-Authorization: Bearer <partnerkey>

Vacatures

Toevoegen

POST https://api.werkzoeken.nl/vacancy
Met behulp van dit request kun je een vacature toevoegen.
Velden
Naam Type Format Verplicht Beschrijving
referenceNumber string required Uniek eigen referentienummer
title string required
description string required
location string required Plaats of postcode
countryCode string (2) ISO 3166 optional
education string optional
experience string optional
employment string optional
hours string optional
salary string optional
industry string optional
company object (companyResource) optional
companyUser object (companyUserResource) optional Sollicitaties worden naar dit e-mailadres verzonden
atsId string optional
autoDeleteDate string ISO 8601 optional
customFields array (customFieldResource) optional
companyResource
Naam Type Format Verplicht Beschrijving
name string required
logoUrl string optional
description string optional
typeId int optional Gebruik waarde uit endpoint "Lijst gebruikersfuncties"
companyUserResource
Naam Type Format Verplicht Beschrijving
name string required
email string required
phone string optional
photoUrl string optional
functionId int optional Gebruik waarde uit endpoint "Lijst types"
customFieldResource
Naam Type Format Verplicht Beschrijving
name string required
value string required
Request
curl https://api.werkzoeken.nl/vacancy \
    -X POST \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json' \
    -d '<payload>'
Response
{
    "vacancyId": "int",
    "vacancyUrl": "string"
}
Voorbeeld payload
{
    "referenceNumber": "REF12345",
    "title": "Senior Software Engineer",
    "description": "We zijn op zoek naar een ervaren Senior Software Engineer om ons groeiende engineeringteam te versterken.",
    "location": "Amsterdam",
    "countryCode": "NL",
    "education": "Bachelor in Computerwetenschappen",
    "experience": "5+ jaar in softwareontwikkeling",
    "employment": "Fulltime",
    "hours": "40 uur per week",
    "salary": "1000-2000 euro per maand",
    "industry": "Informatietechnologie",
    "company": {
        "name": "Voorbeeld Bedrijf",
        "logoUrl": "https:\/\/example.com\/logo.png",
        "description": "Beschrijving over bedrijf",
        "typeId": "1"
    },
    "companyUser": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "0612345678",
        "photoUrl": "https:\/\/example.com\/johndoe.jpg",
        "functionId": "1"
    },
    "atsId": "12345",
    "autoDeleteDate": "2023-12-31",
    "customFields": [
        {
            "name": "frameworks",
            "value": "Laravel, Vue.js"
        }
    ]
}

Wijzigen

PUT https://api.werkzoeken.nl/vacancy/<vacancyid>
Met behulp van dit request kun je een vacature wijzigen.
Velden
Naam Type Format Verplicht Beschrijving
referenceNumber string required Uniek eigen referentienummer
title string required
description string required
location string required Plaats of postcode
countryCode string (2) ISO 3166 optional
education string optional
experience string optional
employment string optional
hours string optional
salary string optional
industry string optional
company object (companyResource) optional
companyUser object (companyUserResource) optional Sollicitaties worden naar dit e-mailadres verzonden
atsId string optional
autoDeleteDate string ISO 8601 optional
customFields array (customFieldResource) optional
companyResource
Naam Type Format Verplicht Beschrijving
name string required
logoUrl string optional
description string optional
typeId int optional Gebruik waarde uit endpoint "Lijst gebruikersfuncties"
companyUserResource
Naam Type Format Verplicht Beschrijving
name string required
email string required
phone string optional
photoUrl string optional
functionId int optional Gebruik waarde uit endpoint "Lijst types"
customFieldResource
Naam Type Format Verplicht Beschrijving
name string required
value string required
Request
curl https://api.werkzoeken.nl/vacancy/<vacancyid> \
    -X PUT \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json' \
    -d '<payload>'
Response
{
    "vacancyId": "int",
    "vacancyUrl": "string"
}
Voorbeeld payload
{
    "referenceNumber": "REF12345",
    "title": "Senior Software Engineer",
    "description": "We zijn op zoek naar een ervaren Senior Software Engineer om ons groeiende engineeringteam te versterken.",
    "location": "Amsterdam",
    "countryCode": "NL",
    "education": "Bachelor in Computerwetenschappen",
    "experience": "5+ jaar in softwareontwikkeling",
    "employment": "Fulltime",
    "hours": "40 uur per week",
    "salary": "1000-2000 euro per maand",
    "industry": "Informatietechnologie",
    "company": {
        "name": "Voorbeeld Bedrijf",
        "logoUrl": "https:\/\/example.com\/logo.png",
        "description": "Beschrijving over bedrijf",
        "typeId": "1"
    },
    "companyUser": {
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "0612345678",
        "photoUrl": "https:\/\/example.com\/johndoe.jpg",
        "functionId": "1"
    },
    "atsId": "12345",
    "autoDeleteDate": "2023-12-31",
    "customFields": [
        {
            "name": "frameworks",
            "value": "Laravel, Vue.js"
        }
    ]
}

Verwijderen

DELETE https://api.werkzoeken.nl/vacancy/<vacancyid>
Met behulp van dit request kun je een vacature verwijderen. Je hebt hiervoor het <vacancyid> nodig dat in de response stond bij het toevoegen van de vacature. 
curl https://api.werkzoeken.nl/vacancy/<vacancyid> \
    -X DELETE \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json'

Inzichten

GET https://api.werkzoeken.nl/vacancy/insight
Met behulp van dit request ben je in staat om inzichten (kliks, sollicitaties etc) van je vacatures op te vragen.
Query Parameters
Name Type Format Verplicht
offset integer optional
limit integer optional
startDate string ISO 8601 optional
endDate string ISO 8601 optional
referenceNumber string Uniek eigen referentienummer
Request
curl https://api.werkzoeken.nl/vacancy/insight \
    -X GET \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json'
Response
{
    "count": "int",
    "offset": "int",
    "limit": "int",
    "rel": {
        "prev": "string",
        "next": "string"
    },
    "items": [
        {
            "vacancyId": "int",
            "referenceNumber": "string",
            "publishDate": "string",
            "status": "int",
            "title": "string",
            "city": "string",
            "runtime": "int",
            "campaign": "string",
            "functionGroup": "string",
            "companyUser": {
                "name": "string",
                "email": "string"
            },
            "clicks": "int",
            "cpc": "float",
            "cost": "float",
            "applications": "int"
        }
    ]
}

Bedrijf

Lijst types

GET https://api.werkzoeken.nl/company/type
Met behulp van dit request kun je de mogelijke bedrijftypes ophalen.
Request
curl https://api.werkzoeken.nl/company/type \
    -X GET \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json'
Response
{
    "count": "int",
    "offset": "int",
    "limit": "int",
    "rel": {
        "prev": "string",
        "next": "string"
    },
    "items": [
        {
            "id": "int",
            "name": "string"
        }
    ]
}

Lijst gebruikersfuncties

GET https://api.werkzoeken.nl/company/user/function
Met behulp van dit request kun je de gebruikerfuncties ophalen.
Request
curl https://api.werkzoeken.nl/company/user/function \
    -X GET \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json'
Response
{
    "count": "int",
    "offset": "int",
    "limit": "int",
    "rel": {
        "prev": "string",
        "next": "string"
    },
    "items": [
        {
            "id": "int",
            "name": "string"
        }
    ]
}

Kliks

Lijst kliks

GET https://api.werkzoeken.nl/click
Met behulp van dit request ben je in staat om alle kliks van je vacatures op te vragen.
Query parameters
Name Type Format Verplicht
offset integer optional
limit integer optional
startDate string ISO 8601 optional
endDate string ISO 8601 optional
referenceNumber string optional
Request
curl https://api.werkzoeken.nl/click \
    -X GET \
    -H 'Authorization: Bearer <apikey>' \ 
    -H 'Content-Type: application/json'
Response
{
    "count": "int",
    "offset": "int",
    "limit": "int",
    "rel": {
        "prev": "string",
        "next": "string"
    },
    "items": [
        {
            "vacancyId": "int",
            "clickDate": "string",
            "referenceNumber": "string",
            "ip": "string",
            "cpc": "float"
        }
    ]
}

Webhooks

Sollicitaties

Webhooks zijn, in tegenstelling tot onze API, endpoints die je zelf zult moeten implementeren.

We bieden de mogelijkheid tot het aanroepen van je webhook zodra er een sollicitatie via Werkzoeken.nl binnen is gekomen. Hieronder vind je de payload die we versturen. We doen een POST request naar de door jou opgegeven endpoint-URL. De payload is een JSON object met onderstaande velden. Het is mogelijk om custom velden toe te voegen.
Zodra je de webhook hebt geïntegreerd dien je contact met ons op te nemen om deze te laten activeren.
Autorisatie
Elke request dient geauthenticeerd te worden. Bij voorkeur werken we met een onderling afgesproken unieke key die we als Bearer in de header toevoegen. Hieronder vind je een voorbeeld. Optioneel kunnen we ook werken met HMAC. 
Authorization: Bearer <apikey>
Velden
Naam Type Format Verplicht Beschrijving
referenceNumber string (255) required Referentienummer van je vacature.
name string (255) required Naam van de kandidaat.
email email (255) required E-mailadres van de kandidaat.
phone string (255) optional Telefoonnummer van de kandidaat.
city string (255) optional Woonplaats van de kandidaat.
motivation text (65.535) optional Motivatie van de kandidaat.
source string (255) required Bron van de sollicitatie (utm-source).
campaign string (255) required Campagne van de sollicitatie (utm-campaign).
cv string base64 encoded string optional Base64 encoded string van het CV bestand (max 20MB).
filename string (255) optional Naam van het CV bestand incl. extensie.
Te verwachte HTTP-statuscodes
HTTP-statuscode Betekenis
201 Created Sollicitatie is succesvol toegevoegd.
400 Bad Request De request is niet succesvol door ongeldige data (graag de reden toevoegen aan de response).
401 Unauthorized Ongeldige autorisatie.
Te verwachte response (een uniek id van de sollicitatie)
{
    "id": 1
}
Voorbeeld payload
{
    "referenceNumber": "f435a426-f656-ea11-a811-000d3a649fc7",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "0612345678",
    "city": "Amsterdam",
    "motivation": "Motivatie",
    "source": "Werkzoeken.nl",
    "campaign": "Transport Campagne",
    "cv": "VBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPD\u2026..(truncated)",
    "filename": "cv.pdf"
}
lijst API inhoud
Algemeen Introductie Rate limits Paginatie HTTP-statuscodes Foutmeldingen
Authenticatie Credentials API key Partner key
Vacatures Toevoegen Wijzigen Verwijderen Inzichten
Bedrijf Lijst types Lijst gebruikersfuncties
Kliks Lijst kliks
Webhooks Sollicitaties
 
Algemeen
Introductie Rate limits Paginatie HTTP-statuscodes Foutmeldingen
Authenticatie
Credentials API key Partner key
Vacatures
Toevoegen Wijzigen Verwijderen Inzichten
Bedrijf
Lijst types Lijst gebruikersfuncties
Kliks
Lijst kliks
Webhooks
Sollicitaties
check
Oeps..!
Er is een onbekend probleem opgetreden. Probeer het nogmaals.
Neem contact met ons op als het probleem blijft ontstaan.
Opnieuw proberen
Test
Annuleer
Ja, ik weet het zeker
check
Sluit melding