API di Hiring: Pattern REST + Bearer Token per Integrazioni di Recruiting

Perché hai bisogno di una API REST

La maggior parte delle piattaforme ATS moderni espongono i dati solo attraverso webhook e una UI nativa. Questo funziona se hai 20 persone e un singolo processo. Ma nel momento in cui vuoi:

• Sincronizzare candidati al tuo sistema HR (BambooHR, Workday) che non ha un'integrazione pre-costruita
• Estrarre report nel tuo data warehouse per analytics personalizzato
• Bulk-importare candidati da un vecchio sistema
• Costruire un dashboard personalizzato che il tuo team preferisce sulla UI nativa
• Automatizzare compiti con Zapier o Make.com senza codice

...hai bisogno di una API REST pubblica.

Una API REST è la lingua franca di integrazione SaaS. Qualunque strumento che parli HTTP può parlarle. Zapier, Make, n8n, Pipedream, script Python personalizzati, app mobile, i tuoi dashboard — tutti possono leggere e scrivere dati con un semplice token di autenticazione.

Il pattern di bearer token

Il pattern API sicuro più semplice è bearer token: emetti a ogni utente una API key, includila nel header Authorization: Bearer YOUR_KEY e ogni richiesta si autentica contro quel key.

Così è come Stripe, GitHub, Slack e la maggior parte delle API moderne funzionano. È facile da revocare (cancella il key) facile da ruotare (genera uno nuovo) e facile da scoped (emetti key diversi con permessi diversi).

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

Confronta questo a username/password o OAuth: i bearer token sono stateless (nessun database di sessione), possono essere invalidati istantaneamente e ti permettono di audit quale key ha fatto quale richiesta.

Scope e permessi

Una best practice di sicurezza: non emettere token con accesso full read-write a tutto. Invece usa scope.

candidates:read       # Può list e view candidati
candidates:write      # Può muovere candidati, aggiungere note
tests:read            # Può view risultati di test
tests:write           # Può creare e edit test
jobs:read             # Può list lavori
webhooks:manage       # Può creare/cancellare webhook

Quando uno sviluppatore di terze parti richiede accesso API (per dire un fornitore HRIS che si integra con la tua piattaforma), emetti loro un token con solo candidates:read e candidates:write. Non possono vedere i tuoi dati di fatturazione o modificare domande di intervista.

Gli scope anche proteggono da danno accidentale. Se uno script di integrazione ha un bug e inizia a cancellare candidati, lo noti più veloce se lo script dovrebbe solo avere candidates:read.

Webhook vs. polling

Due pattern per mantenere dati in sincronizzazione:

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

Quando qualcosa accade in ClarityHire, posta al tuo endpoint. Processa immediatamente. Veloce, efficiente, nessun overhead di polling.

Polling (pull-based):

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

Periodicamente (ogni 5 minuti, ogni ora) chiedi a ClarityHire "cosa è cambiato?" e processa la risposta. Più semplice da implementare se il tuo sistema non espone un endpoint HTTP, ma più lento e più rumoroso.

Best practice: webhook per real-time (cambio stage, nuove applicazioni), polling per sync periodici (export giornaliero di tutti i candidati al tuo data warehouse).

Entrambi i pattern dovrebbero supportare retry logic. I webhook possono fallire (outage di rete, tuo endpoint giù). L'API dovrebbe riprovare con exponential backoff e lasciarti vedere i tentativi falliti in un dashboard "webhook log".

Rate limit e idempotenza

Quando esponi un'API hai bisogno di safeguard contro abuso e duplicati accidentali.

Rate limit: "Puoi fare 1.000 richieste per ora per API key." Se qualcuno supera, ottiene una risposta 429 con header Retry-After. Zapier e altre piattaforme di integrazione rispettano automaticamente questi limiti.

Idempotenza: Se una consegna di webhook fallisce riproviamo. Ma cosa se la richiesta davvero ha avuto successo ma la risposta si è tirata su? Senza idempotenza creeremmo un candidato duplicato o muoveremmo il candidato due volte.

Soluzione: richiedi un header Idempotency-Key su richieste di scrittura.

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

L'API memorizza il key e la risposta. Se lo stesso key è usato di nuovo ritorna la risposta in cache. Nessun duplicato.

Documentazione e SDK

Una API è inutile senza docs. Hai bisogno di:

1. Endpoint reference: ogni rotta, ogni parametro, ogni formato di risposta
2. Codici di errore: cosa significa un 400? un 403?
3. Tipi di evento webhook: lista completa di eventi che emetti, con payload di esempio
4. Esempi di codice: snippet curl, Python, JavaScript per compiti comuni
5. Autenticazione: come generare e ruotare key

Bonus: pubblica SDK per linguaggi popolari (Python, JavaScript, Go). Zapier viene con SDK built-in, ma integrazioni personalizzate beneficiano da una libreria client nativa che gestisce paginazione, riprove e gestione degli errori.

Integrazione Zapier: leverage di livello successivo

Zapier connette centinaia di app senza codice. Una volta esponi una API REST, scrivere un'integrazione Zapier diventa un progetto di 1-2 settimane invece di 4 settimane custom build.

Esempio Zap:

• Trigger: "Nuovo candidato in lavoro di ClarityHire 'Senior Backend Engineer'"
• Azione 1: "Aggiungi riga a Google Sheets"
• Azione 2: "Invia messaggio Slack a #hiring"
• Azione 3: "Crea contatto in Pipedrive"

Un utente Zapier imposta questo con zero codice. Altri utenti Zapier lo scoprono nel marketplace Zapier e l'adottano. Hai costruito un ecosistema di 100 integrazioni senza scrivere 100 integrazioni.

Come ClarityHire espone la sua API

ClarityHire offre /api/v1/* con autenticazione bearer token, permessi scoped e supporto webhook. I doc di riferimento vivono a api.clarityhire.com/docs. Rate limit: 1.000 richieste/ora per key. Scritte idempotenti con header Idempotency-Key.

Endpoint di esempio:

• GET /api/v1/candidates — list candidati (supporta filtro, paginazione)
• GET /api/v1/candidates/{id} — candidato singolo
• POST /api/v1/candidates/{id}/move-stage — transizione di stage
• GET /api/v1/webhooks — list i tuoi webhook attivi
• POST /api/v1/webhooks — registra un webhook nuovo

I webhook possono essere filtrati per tipo di evento, job_id o organizzazione. Il sistema riprova le consegne fallite 10 volte su 24 ore con exponential backoff.

TL;DR

Una API REST pubblica con bearer token sblocca integrazioni. Scope i permessi per caso d'uso. Preferisci webhook per sincronizzazione real-time, polling per export di batch. Applica idempotenza su scritture per prevenire duplicati. Documenta a fondo, incluso codici di errore ed esempi. L'integrazione Zapier è il moltiplicatore: una API abilita mille casi d'uso senza il tuo team che li codifica.

L'investimento nel design di API paga dividendi in flessibilità e adozione.