Hiring API: REST + Bearer Token Pattern Integrări Recrutare

De ce trebuie REST API

Platforme ATS moderne expun date doar webhook și native UI. Asta lucru 20 persoane și proces unic. Dar moment vrei:

• Sync candidați sistem HR (BambooHR, Workday) ce nu pre-built integrare
• Pull raport date warehouse custom analytics
• Bulk-import candidați sistem vechi
• Crea custom dashboard echipă preferi native UI
• Automate task Zapier sau Make.com fără scri cod

...trebuie REST API public.

REST API-ul e lingua franca SaaS integrare. Orice tool vorbesc HTTP poți vorbesc asta. Zapier, Make, n8n, Pipedream, Python script custom, app mobile, propriul dashboard—toți citit și scri date simple authentication token.

Bearer token pattern

Simplist secure API pattern-u bearer token: emitere fiecare utilizator API key, includ Authorization: Bearer YOUR_KEY header și fiecare cerere authenticate token ăsta.

Asta cum Stripe, GitHub, Slack și prim API moderne lucru. Ușor revoca (șterge key), ușor rotate (generează nou) și ușor scope (emitere diferit key diferit permis).

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

Compara username/parola sau OAuth: bearer token stateless (sesiune bază date), invalida instant și audit care key cerere ce.

Scop și permis

Securitate best practice: nu emitere token full read-write acces totul. Înlocuitor, foloseşte scop.

candidates:read       # Poți list și view candidați
candidates:write      # Poți mută candidați, adaugă note
tests:read            # Poți view rezultate test
tests:write           # Poți creia și edit test
jobs:read             # Poți list job
webhooks:manage       # Poți creia/șterge webhook

Terț-party dev cere API acces (spune, HRIS provider integrate platforma), emitere token doar candidates:read și candidates:write. Nu pot vede billing date sau modifica interviu întrebări.

Scop protect și contra daună accident. Dacă script integrare bug și start șterge candidați, spot mai rapid dacă script nevoie doar candidates:read.

Webhook vs. polling

Două pattern sync date:

Webhook (event-driven):

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

Se întâmplă ceva ClarityHire, post endpoint tău. Process imediat. Rapid, eficient, polling overhead niciun.

Polling (pull-based):

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

Periodic (fiecare 5 min, fiecare oră) cere ClarityHire-ul "ce schimbat?" și process răspuns. Simplist implement dacă sistem nu expose HTTP endpoint dar mai lent și noise.

Best practice: webhook real-time (etapă schimbare, aplicații nouă), polling periodic export (daily export tote candidați date warehouse).

Amândoi pattern trebuie suporta retry logic. Webhook poți fail (outage rețea, endpoint tău down). API trebuie retry exponential backoff și lasă vede failed tentative webhook log dashboard.

Rate limit și idempotență

Expui API trebuie safeguard abuż și duplicate accident.

Rate limit: "Poti face 1.000 cerere per oră per API key." Depăși asta, primești 429 răspuns cu Retry-After header. Zapier și alt integrare platform respect limit asta automat.

Idempotență: Webhook delivery fail, retry asta. Dar ce dacă cerere actual reusit dar răspuns timeout? Fără idempotență, crei duplicate candidat sau mută candidat două.

Soluție: cere Idempotency-Key header cerere scri.

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"}'

API store key și răspuns. Același key folosit din nou, returnează cached răspuns. Duplicate niciunu.

Documentație și SDK

API useless fără doc. Trebuie:

1. Endpoint reference: fiecare rută, fiecare parametru, format răspuns
2. Error cod: 400 înseamnă ce? 403?
3. Webhook event tip: listă complet event emit, payload exemplu
4. Cod exemplu: curl, Python, JavaScript snippet sarcini comun
5. Autentificare: cum generează și rotate key

Bonus: publish SDK limbi popular (Python, JavaScript, Go). Zapier vine built-in SDK dar custom integrări benefitează native client bibliotecă handle pagination, retry și error handling.

Zapier integrare: next-level leverage

Zapier conectă sute app fără cod. O dată expui REST API, scriere Zapier integrare devine 1-2 week proiect insteadof 4 săptămâni custom build.

Exemplu Zap:

• Trigger: "Candidat nouă ClarityHire job 'Senior Backend Engineer'"
• Action 1: "Adaugă rând Google Sheet"
• Action 2: "Trimite Slack mesaj #hiring"
• Action 3: "Creia contact Pipedrive"

Unu Zapier utilizator setup asta zero coding. Alt Zapier utilizatori descoperă marketplace Zapier și adopt. Ai construit 100-integrare ecosistem fără scri 100 integrări.

Cum ClarityHire expune API

ClarityHire ofertă /api/v1/* bearer token auth, permis scop și webhook suporta. Referință doc trăi api.clarityhire.com/docs. Rate limit: 1.000 cerere/oră per key. Scri idempotent cu Idempotency-Key header.

Exemplu endpoint:

• GET /api/v1/candidates — list candidați (suporta filtrare, pagination)
• GET /api/v1/candidates/{id} — candidat unic
• POST /api/v1/candidates/{id}/move-stage — etapă tranzițîe
• GET /api/v1/webhooks — list active webhook
• POST /api/v1/webhooks — registru webhook nouă

Webhook poți filtrare event tip, job_id sau organizație. Sistem retry failed delivery 10 timp 24 ore exponential backoff.

TL;DR

REST API public bearer token unlock integrări. Scop permis caz utz. Preferi webhook real-time sync, polling batch export. Enforce idempotență scri preventiva duplicate. Documentare bine includ cod error și exemplu. Zapier integrare multiplicator: unu API enable mie cazuri fără echipă kod.

Investiție API design vinde dividend flexibilitate și adopție.