API Referentie

Volledige referentie voor alle Recruitsome API endpoints. Elk onderdeel linkt naar het bijbehorende artikel met voorbeelden en response bodies.

Base URL

Code

https://app.recruitsome.com/api/v1

Authenticatie

Alle endpoints vereisen Bearer token-authenticatie:

Code

Authorization: Bearer YOUR_API_KEY

Elk endpoint (behalve de health check) vereist ook een specifieke scope op je API sleutel. Deze staat hieronder per endpoint vermeld. Een sleutel zonder de juiste scope krijgt een 403 met de foutcode INSUFFICIENT_SCOPE.

Endpoints

Health Check

GET/health

Verifieer API-authenticatie en tenantcontext

Scope: geen — elke geldige API sleutel

Response:

JSON

{
  "status": "authenticated",
  "tenant": "tenant-id"
}

Gepubliceerde vacatures ophalen

GET/vacancies

Haal een gepagineerde lijst van gepubliceerde vacatures op

Scope: vacancies:read

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`page`	integer	1	Paginanummer
`per_page`	integer	20	Items per pagina (max: 100)
`language`	string	-	Filter op taalcode
`location_id`	integer	-	Filter op locatie-ID
`department_id`	integer	-	Filter op afdeling-ID
`company_location_id[]`	array	-	Filter op bedrijfslocatie-ID's
`search`	string	-	Zoek in titel en samenvatting
`job_types[]`	array	-	Filter op dienstverband-ID's
`experience_levels[]`	array	-	Filter op ervaringsniveau-ID's
`education_levels[]`	array	-	Filter op opleidingsniveau-ID's
`tags[]`	array	-	Filter op tag-ID's (hoofdtags omvatten automatisch subtags)
`sort`	string	published_at	Sorteerveld: `published_at`, `title`, `created_at`
`sort_direction`	string	desc	Sorteerrichting: `asc` of `desc`
`include`	string	-	Aanvullende data meenemen: `facets`
`include_media`	boolean	false	Headerafbeelding-URL's meenemen
`include_compensation`	boolean	false	Salarisgegevens meenemen
`include_company_name`	boolean	false	Bedrijfsnaam meenemen

Response: Gepagineerde lijst van vacatures, zie Gepubliceerde vacatures ophalen

Vacaturefacetten ophalen

GET/vacancies/facets

Haal filterfacetten met tellingen op voor vacaturepublicaties

Scope: vacancies:read

Query Parameters: Dezelfde filterparameters als bij het ophalen van vacatures (worden toegepast vóór het tellen)

Response: Facettellingen voor locaties, afdelingen, dienstverbanden, ervaringsniveaus, opleidingsniveaus, tags en talen, zie Vacaturefacetten ophalen

Vacaturedetails ophalen

GET/vacancies/{slug}

Haal volledige informatie op voor een specifieke vacature

Scope: vacancies:read

Path Parameters:

Parameter	Type	Verplicht	Beschrijving
`slug`	string	Ja	URL-vriendelijke vacature-identifier

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`language`	string	-	Stel de taal in voor vertaalde labels in de response
`include_compensation`	boolean	false	Salarisgegevens meenemen
`include_media`	boolean	false	Headerafbeelding-URL's meenemen
`include_company_name`	boolean	false	Bedrijfsnaam meenemen

Response: Volledige vacaturedetails inclusief de volledige inhoud, zie Vacaturedetails ophalen

Vacature-URL rapporteren

POST/vacancies/{slug}/canonical-url

Rapporteer de canonical publieke URL die je website aan een vacature heeft toegekend

Scope: vacancies:write

Path Parameters:

Parameter	Type	Verplicht	Beschrijving
`slug`	string	Ja	De `publication_slug` van de vacature

Body:

Veld	Type	Verplicht	Beschrijving
`url`	string	Ja	De volledige canonical URL op je website. Moet beginnen met `https://` (max 2048 tekens) en op het domein van je carrièrewebsite staan

Response: Bevestiging met de opgeslagen URL. Gerapporteerde URL's hebben voorrang op het geconfigureerde URL-patroon, zie Vacature-URL rapporteren

Sollicitatie indienen

POST/applications

Dien een sollicitatie in voor een gepubliceerde vacature

Scope: applications:write — beperkt tot 10 verzoeken per minuut

Body:

Veld	Type	Verplicht	Beschrijving
`vacancy`	string of integer	Ja	De slug of het ID van de vacature
`candidate`	object	Ja	Kandidaatgegevens: `given_name`, `family_name` en `email` zijn verplicht; `linkedin_url`, `mobile_phone` en `fixed_phone` zijn optioneel
`documents`	object	Nee	Optioneel `resume`, `cover_letter` en maximaal 5 `additional` documenten (base64-gecodeerd)
`privacy_policy_accepted`	boolean	Nee	Of de kandidaat je privacybeleid heeft geaccepteerd
`tracking`	object	Nee	Optioneel `ip_address`, `user_agent` en `referrer`

Response: 201 met de aangemaakte sollicitatie, zie Sollicitatie indienen

Locaties ophalen

GET/locations

Haal een gepagineerde lijst van kantoorlocaties op

Scope: locations:read

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`page`	integer	1	Paginanummer
`per_page`	integer	20	Items per pagina (max: 100)
`language`	string	-	Stel de taal in voor landnamen in de response
`country_code`	string	-	Filter op landcode
`search`	string	-	Zoek in naam, stad en adres
`sort`	string	name	Sorteerveld: `name`, `locality`, `created_at`
`sort_direction`	string	asc	Sorteerrichting: `asc` of `desc`
`include_coordinates`	boolean	false	Breedte- en lengtegraad meenemen
`include_vacancy_count`	boolean	false	Aantal vacatures meenemen

Response: Gepagineerde lijst van locaties met adressen, zie Locaties ophalen

Locatiedetails ophalen

GET/locations/{slug}

Haal volledige informatie op voor een specifieke locatie

Scope: locations:read

Path Parameters:

Parameter	Type	Verplicht	Beschrijving
`slug`	string	Ja	URL-vriendelijke locatie-identifier

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`language`	string	-	Stel de taal in voor landnamen in de response
`include_coordinates`	boolean	false	Breedte- en lengtegraad meenemen
`include_vacancy_count`	boolean	false	Aantal vacatures meenemen

Response: Volledige locatiedetails, zie Locatiedetails ophalen

Teamleden ophalen

GET/team

Haal een gepagineerde lijst van actieve teamleden op

Scope: team:read

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`page`	integer	1	Paginanummer
`per_page`	integer	20	Items per pagina (max: 100)
`search`	string	-	Zoek in naam, e-mailadres en functietitel
`job_title`	string	-	Filter op functietitel
`role`	string	-	Filter op rolnaam
`has_avatar`	boolean	false	Alleen leden met een avatar
`sort`	string	given_name	Sorteerveld: `given_name`, `family_name`, `job_title`
`sort_direction`	string	asc	Sorteerrichting: `asc` of `desc`
`include_phone`	boolean	false	Telefoonnummer meenemen
`include_role`	boolean	false	Rollabel meenemen

Response: Gepagineerde lijst van teamleden met avatars, zie Teamleden ophalen

Teamliddetails ophalen

GET/team/{id}

Haal volledige informatie op voor een specifiek teamlid

Scope: team:read

Path Parameters:

Parameter	Type	Verplicht	Beschrijving
`id`	integer	Ja	Teamlid-ID

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`include_phone`	boolean	false	Telefoonnummer meenemen
`include_role`	boolean	false	Rollabel meenemen

Response: Volledige teamliddetails, zie Teamliddetails ophalen

Kandidaten ophalen

GET/candidates

Haal een gepagineerde lijst op van kandidaten die aan een gebruiker zijn gekoppeld

Scope: candidates:read

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`user_id`	integer	verplicht	Alleen kandidaten die aan deze gebruiker zijn gekoppeld worden geretourneerd
`email`	string	-	Filter op e-mailadres (exacte match)
`search`	string	-	Zoek in voornaam, achternaam en e-mailadres
`status`	string	-	Filter op kandidaatstatus
`sort`	string	created_at	Sorteerveld: `created_at`, `first_name`, `last_name`, `email`
`sort_direction`	string	desc	Sorteerrichting: `asc` of `desc`
`per_page`	integer	20	Items per pagina (max: 100)

Response: Gepagineerde lijst van kandidaten, zie Kandidaten ophalen

Kandidaat aanmaken

POST/candidates

Maak een kandidaat aan via cv-upload (asynchroon)

Scope: candidates:write — beperkt tot 10 verzoeken per minuut

Body:

Veld	Type	Verplicht	Beschrijving
`user_id`	integer	Ja	De gebruiker waaraan de kandidaat wordt gekoppeld
`resume`	object	Ja	Het cv: `filename`, `content` (base64-gecodeerd) en `mime_type` (PDF, DOC of DOCX, max 10 MB)
`create_intake`	boolean	Nee	Maak ook een intake aan voor de kandidaat

Response: 202 met een processing_id. De kandidaat wordt op de achtergrond aangemaakt op basis van het cv. Zie Kandidaat aanmaken

Artikelen ophalen

GET/articles

Haal een gepagineerde lijst van gepubliceerde artikelen op

Scope: articles:read

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`page`	integer	1	Paginanummer
`per_page`	integer	20	Items per pagina (max: 100)
`language`	string	-	Filter op taalcode
`type`	string	-	Filter op type: `news`, `company_update`, `event`, `blog_post`
`search`	string	-	Zoek in titel en samenvatting
`tags[]`	array	-	Filter op tag-ID's (hoofdtags omvatten automatisch subtags)
`is_featured`	boolean	-	Alleen uitgelichte artikelen
`sort`	string	published_at	Sorteerveld: `published_at`, `title`, `created_at`, `views_count`
`sort_direction`	string	desc	Sorteerrichting: `asc` of `desc`
`include_media`	boolean	false	Uitgelichte afbeelding-URL's meenemen

Response: Gepagineerde lijst van artikelen, zie Artikelen ophalen

Artikeldetails ophalen

GET/articles/{slug}

Haal volledige informatie op voor een specifiek artikel

Scope: articles:read

Path Parameters:

Parameter	Type	Verplicht	Beschrijving
`slug`	string	Ja	URL-vriendelijke artikelcontent-identifier

Query Parameters:

Parameter	Type	Standaard	Beschrijving
`language`	string	-	Stel de taal in voor de response
`include_media`	boolean	false	Uitgelichte afbeelding-URL's meenemen

Response: Volledige artikeldetails inclusief de volledige body-HTML en SEO-metadata, zie Artikeldetails ophalen

Statuscodes

Code	Beschrijving
200	Geslaagd
201	Aangemaakt (sollicitatie ingediend)
202	Geaccepteerd (cv van kandidaat in wachtrij voor verwerking)
400	Ongeldig verzoek (bedrijfsregel mislukt, bijv. vacature gesloten)
401	Niet geautoriseerd
403	Geen toegang (ontbrekende scope)
404	Niet gevonden
422	Validatiefout
429	Snelheidslimiet bereikt
500	Serverfout

Snelheidslimieten

POST /vacancies/{slug}/canonical-url: 60 verzoeken per minuut per API sleutel
POST /applications en POST /candidates: 10 verzoeken per minuut per API sleutel
Lees-endpoints hebben op dit moment geen vaste limiet per sleutel. Houd je aantal verzoeken beperkt; limieten kunnen later worden ingevoerd.
Endpoints met snelheidslimieten bevatten de headers X-RateLimit-Limit en X-RateLimit-Remaining in hun responses.

Ondersteuning

Heb je vragen? Stuur ons een e-mail op [email protected] of bekijk de rest van het Helpcentrum.

Base URL

Authenticatie

Endpoints

Health Check

Gepubliceerde vacatures ophalen

Vacaturefacetten ophalen

Vacaturedetails ophalen

Vacature-URL rapporteren

Sollicitatie indienen

Locaties ophalen

Locatiedetails ophalen

Teamleden ophalen

Teamliddetails ophalen

Kandidaten ophalen

Kandidaat aanmaken

Artikelen ophalen

Artikeldetails ophalen

Statuscodes

Snelheidslimieten

Ondersteuning

Lees ook