RecruitSome API

De RecruitSome API biedt programmatische toegang tot gepubliceerde vacaturedata, waardoor naadloze integratie met je recruitmentplatformen, jobboards en HR-systemen mogelijk wordt.

Base URL

Alle API-verzoeken dienen te worden verstuurd naar:

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

Authenticatie

De RecruitSome API maakt gebruik van Bearer token-authenticatie. Je dient je API key mee te sturen in de Authorization header van elk verzoek.

Authorization: Bearer YOUR_API_KEY

Aan de slag

1. Een API Key genereren

Om de RecruitSome API te gebruiken, moet je eerst een API key genereren vanuit je tenant-dashboard:

1. Log in op je RecruitSome-account
2. Navigeer naar Settings → Integrations → API Keys
3. Klik op Create API Key
4. Geef je API key een beschrijvende naam (bijv. "Production Integration" of "Development Testing")
5. Klik op Generate Key
6. Belangrijk: Kopieer en bewaar je API key direct op een veilige plek. Om veiligheidsredenen kun je deze daarna niet meer inzien.

API Key-machtigingen

Elke API key kan worden beperkt tot specifieke machtigingen, volgens het principe van minimale rechten. Selecteer bij het aanmaken van een key alleen de machtigingen die je integratie nodig heeft:

• Carrièrewebsite: vacatures, sollicitaties, locaties, team, artikelen
• Chrome Plugin: kandidaten (read + write), team

Als een verzoek wordt gedaan naar een endpoint waartoe de API key geen toegang heeft, wordt een 403 Forbidden-respons met de INSUFFICIENT_SCOPE-foutcode geretourneerd.

2. Je eerste verzoek doen

Laten we je API key testen 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 voor optimale prestaties. De API maakt gebruik van cursor-gebaseerde paginering met de volgende parameters:

Structuur van de pagineringsrespons

{
  "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

Om eerlijk gebruik te waarborgen en de servicekwaliteit te behouden:

• API-verzoeken zijn beperkt tot 60 verzoeken per minuut
• Rate limit-informatie wordt meegestuurd in de responsheaders:

- X-RateLimit-Remaining: Resterende verzoeken in het huidige tijdsvenster

- X-RateLimit-Reset: Unix-timestamp waarop de limiet wordt gereset

Responsformaten

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

Succesvolle respons

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

Foutrespons

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

HTTP-statuscodes

Volgende stappen

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