Introductie

De Recruitsome API geeft je programmatische toegang tot je gepubliceerde vacaturedata. Zo kun je je carrièrewebsite, jobboards en HR-integraties rechtstreeks vanuit Recruitsome aansturen.

Base URL

Alle API-verzoeken gaan naar:

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

Authenticatie

De Recruitsome API maakt gebruik van Bearer-tokenauthenticatie. Voeg je API sleutel toe aan de Authorization-header van elk verzoek:

Authorization: Bearer YOUR_API_KEY

Aan de slag

1. Een API sleutel aanmaken

1. Log in op je Recruitsome-account
2. Ga naar Instellingen → API Sleutels
3. Klik op API Sleutel Aanmaken (of Maak je eerste API Sleutel aan als je nog geen sleutels hebt)
4. Kies een preset onder Quick Setup, of selecteer individuele Permissions
5. Geef je sleutel een beschrijvende Sleutelnaam (bijv. "Carrièrewebsite" of "Indeed Plugin")
6. Klik op API Sleutel Aanmaken

Je nieuwe sleutel verschijnt eenmalig in het Nieuwe API Sleutel Gegenereerd-venster. Kopieer de sleutel direct. Om veiligheidsredenen wordt deze niet opnieuw getoond.

API sleutel-permissies

Elke API sleutel is beperkt tot specifieke permissies, volgens het principe van minimale rechten. Selecteer bij het aanmaken van een sleutel alleen de permissies die je integratie nodig heeft:

Presets zijn beschikbaar voor veelvoorkomende toepassingen:

• Carrièrewebsite: vacatures (lezen + schrijven), sollicitaties, locaties, team, artikelen
• Chrome Plugin: kandidaten (lezen + schrijven), team
• Volledige Toegang: alle beschikbare permissies

Als je een endpoint aanroept waarvoor je API sleutel geen toegang heeft, ontvang je een 403 Forbidden-respons met de foutcode INSUFFICIENT_SCOPE.

2. Je eerste verzoek doen

Test je API sleutel met een eenvoudige health check:

curl -X GET https://app.recruitsome.com/api/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

Een succesvolle respons ziet er als volgt uit:

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

Paginering

Alle lijst-endpoints retourneren gepagineerde resultaten. De API maakt gebruik van paginering op basis van paginanummers. Vraag een specifieke pagina op met de page-parameter en lees je positie uit het meta-object:

Structuur van het pagineringsantwoord

{
  "data": [...],
  "links": {
    "first": "https://app.recruitsome.com/api/v1/vacancies?page=1",
    "last": "https://app.recruitsome.com/api/v1/vacancies?page=5",
    "prev": null,
    "next": "https://app.recruitsome.com/api/v1/vacancies?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://app.recruitsome.com/api/v1/vacancies",
    "per_page": 20,
    "to": 20,
    "total": 95
  }
}

Voorbeeld: door pagina's itereren

let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await fetch(
    `https://app.recruitsome.com/api/v1/vacancies?page=${page}&per_page=50`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const data = await response.json();

  // Process the vacancies
  processVacancies(data.data);

  // Check if there are more pages
  hasMore = data.meta.current_page < data.meta.last_page;
  page++;
}

Rate limiting

Drie write-endpoints hebben een rate limit omdat ze zwaardere verwerking triggeren:

De read-endpoints hebben op dit moment geen vaste limiet per sleutel. Houd je aantal verzoeken wel beperkt en cache responses waar mogelijk. Er kunnen in de toekomst limieten worden ingesteld.

Endpoints met rate limiting bevatten de volgende headers in hun responses:

• X-RateLimit-Limit: maximaal aantal verzoeken per minuut
• X-RateLimit-Remaining: resterende verzoeken in het huidige tijdvenster

Wanneer je de limiet overschrijdt, bevat de 429-response ook:

• Retry-After: aantal seconden om te wachten voordat je het opnieuw probeert
• X-RateLimit-Reset: Unix-timestamp waarop de limiet wordt gereset

Responseformaten

Alle API-responses worden geretourneerd in JSON-formaat met UTF-8-codering.

Succesvolle response

{
  "data": {
    // Response data
  }
}

Foutresponse

{
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}

HTTP-statuscodes

Volgende stappen

• Gepubliceerde vacatures ophalen - Leer hoe je vacatureoverzichten ophaalt en filtert
• Vacaturedetails ophalen - Bekijk volledige vacature-informatie
• API Reference - Volledige documentatie van alle API endpoints