Werving API: Een REST + Bearer Token Patroon voor Werving Integraties

Waarom je een REST API nodig

De meeste moderne ATS platforms gegevens slechts via webhooks en een inheemse UI bloot. Dat werkt als je 20 personen en enkel proces hebt. Maar het moment je wilt:

• Sync kandidaten naar je HR systeem (BambooHR, Workday) die geen pre-gebouwd integratie heeft
• Trek rapporten in je data magazijn voor aangepast analytische
• Bulk-import kandidaten van oud systeem
• Bouw een aangepast dashboard die je team inheems UI voorkeur
• Automatiseer taken met Zapier of Make.com zonder codering

...je hebt een publieke REST API nodig.

Een REST API is de lingua franca van SaaS integratie. Elk gereedschap dat HTTP spreekt kan met het praten. Zapier, Make, n8n, Pipedream, aangepaste Python scripts, mobiele app's, je eigen dashboards — zij allemaal kunnen gegevens lezen en schrijven met eenvoudige authenticatie token.

Het draagtoken patroon

Het eenvoudigste veilig API patroon is draagtoken's: je geven elk gebruiker een API sleutel, zij omvat het in de Authorization: Bearer JE_SLEUTEL kop, en elk verzoek authenticeert tegen die sleutel.

Dit is hoe Stripe, GitHub, Slack, en de meeste moderne API's werken. Het's makkelijk te herroepen (verwijder de sleutel), makkelijk naar roulette (genereren nieuw), en makkelijk naar scope (geven verschillende sleutels met verschillende toestemmingen).

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  https://api.clarityhire.com/v1/candidates?job_id=j_engineering_2026

Vergelijk dat met gebruikersnaam/wachtwoord of OAuth: draagtokens zijn stateless (geen sessie database), kunnen onmiddellijk ongeldig gemaakt, en laat je controleer welke sleutel welk verzoek maakte.

Scopes en toestemmingen

Een veiligheid best practice: geven niet tokens met volledige lees-schrijf toegang naar alles. In plaats daarvan, gebruik scopes.

candidates:read       # Kan kandidaten lijst en bekijk
candidates:write      # Kan kandidaten verplaats, voeg notities toe
tests:read            # Kan test resultaten bekijk
tests:write           # Kan tests creëren en bewerk
jobs:read             # Kan functies lijst
webhooks:manage       # Kan webhooks creëren/verwijder

Wanneer een derde partij developer API toegang verzoekt (zeggen, een HRIS provider integratie met je platform), je geven hun een token met slechts candidates:read en candidates:write. Ze kunnen je factuur data of änder interview vragen niet zien.

Scopes ook beschermen tegen onopzettelijke schade. Als integratie script heeft fout en begint kandidaten te verwijderen, je spot het sneller als script zou slechts candidates:read moeten hebben.

Webhooks tegen polling

Twee patronen voor houden gegevens in sync:

Webhooks (event-gedreven):

POST https://je-systeem.com/webhook/clarityhire
{
  "event": "candidate.stage_changed",
  "data": {
    "candidate_id": "c_123",
    "old_stage": "screening",
    "new_stage": "assessment",
    "timestamp": "2026-05-21T14:30:00Z"
  }
}

Wanneer iets in ClarityHire gebeurt, het post naar je eindpunt. Je process het onmiddellijk. Snel, efficiënt, geen polling overhead.

Polling (trek-gebaseerd):

GET https://api.clarityhire.com/v1/candidates?job_id=j_123&updated_since=2026-05-21T00:00:00Z

Je periodiek (elke 5 minuten, elk uur) vraag ClarityHire "wat veranderde?" en process antwoord. Eenvoudiger te implementeer als je systeem niet een HTTP eindpunt bloot, maar langzamer en lawaaierig.

Best practice: webhooks voor real-time (stadium wijzigt, nieuwe applicaties), polling voor periodieke syncs (dagelijks export alle kandidaten naar je data magazijn).

Beide patronen zouden retry logica ondersteunen. Webhooks kunnen mislukken (netwerk uitval, je eindpunt neer). De API zou opnieuw probeer met exponentiële back-off en laat je zien mislukt pogingen in een "webhook logs" dashboard.

Tarief limieten en idempotentie

Wanneer je een API bloot, je moet safeguards tegen misbruik en onopzettelijke duplicaten.

Tarief limieten: "Je kunt 1.000 verzoeken per uur per API sleutel maken." Als iemand het overschrijdt, zij krijgen een 429 antwoord met een Retry-After kop. Zapier en ander integratie platforms respecteer dit automatisch.

Idempotentie: Wanneer een webhook bezorging mislukt, we opnieuw probeer het. Maar wat als het verzoek werkelijk slaagde, maar antwoord timing uit? Zonder idempotentie, we zouden dubbel kandidaat creëren of kandidaat twee keer verplaatsen.

Oplossing: vereisen een Idempotency-Key kop op schrijven verzoeken.

curl -H "Authorization: Bearer sk_live_abc123xyz" \
  -H "Idempotency-Key: zap_12345_attempt_1" \
  -X POST https://api.clarityhire.com/v1/candidates \
  -d '{"email": "[email protected]", "job_id": "j_eng"}'

De API slaat sleutel en antwoord op. Als dezelfde sleutel opnieuw gebruikt, het keert cached antwoord terug. Geen duplicaten.

Documentatie en SDK's

Een API is nutteloos zonder documenten. Je nodig:

1. Eindpunt referentie: elk kans, elk parameter, elk antwoord format
2. Fout code's: wat betekent 400? een 403?
3. Webhook event type's: volledige lijst event's je zend, met voorbeeld payloads
4. Code voorbeeld's: curl, Python, JavaScript snippets voor veel voorkomende taken
5. Authenticatie: hoe sleutels genereer en roulette

Bonus: publiek SDK's voor populaire language's (Python, JavaScript, Go). Zapier komt met ingebouwd SDK, maar aangepaste integraties voordeel van inheemse client bibliotheek die paginering, retry's, en fout handeling afhandelt.

Zapier integratie: next-niveau leverage

Zapier verbindt honderd apps zonder codering. Eenmaal je bloot REST API, schrijven Zapier integratie wordt 1-2 week project in plaats van 4-week aangepast gebouw.

Voorbeeld Zap:

• Trigger: "Nieuwe kandidaat in ClarityHire functie 'Senior Backend Engineer'"
• Actie 1: "Rij voeg naar Google Sheets"
• Actie 2: "Stuur Slack bericht naar #werving"
• Actie 3: "Creëer contact in Pipedrive"

Één Zapier gebruiker zet dit op met nul codering. Ander Zapier gebruikers ontdekken het in Zapier marktplaats en nemen aan. Je creeerde 100-integratie ecosysteem zonder 100 integraties schrijven.

Hoe ClarityHire zijn API bloot

ClarityHire biedt /api/v1/* met draagtoken authenticatie, scoped toestemmingen, en webhook ondersteuning. De referentie documenten leven op api.clarityhire.com/docs. Tarief grens: 1.000 verzoeken/uur per sleutel. Idempotent schrijft met Idempotency-Key kop.

Voorbeeld eindpunten:

• GET /api/v1/candidates — kandidaten lijst (ondersteuning filtering, paginering)
• GET /api/v1/candidates/{id} — enkele kandidaat
• POST /api/v1/candidates/{id}/move-stage — stadium overgang
• GET /api/v1/webhooks — je actieve webhooks lijst
• POST /api/v1/webhooks — registreer nieuwe webhook

Webhooks kunnen gefilterd per event type, job_id, of organisatie. Het systeem opnieuw probeer mislukte bezorgingen 10 keer meer dan 24 uren met exponentiële back-off.

TL;DR

Publieke REST API met draagtoken's ontsluit integraties. Scope toestemmingen per use case. Voorkeur webhooks voor real-time sync, polling voor batch exports. Forceer idempotentie op schrijft duplicaten voorkomen. Documenten grondslag, inclusief fout code's en voorbeeld's. Zapier integratie is vermenigvuldiger: één API mogelijk duizend use cases zonder je team codering.

De investering in API ontwerp betaalt dividend in flexibiliteit en aanname.