Produkt

Hiring-API: Ein REST + Bearer-Token Muster für Recruiting-Integrationen

ClarityHire Team(Editorial)2026-05-215 min read

Warum Sie eine REST-API benötigen

Die meisten modernen ATS-Plattformen exponieren Daten nur durch Webhooks und eine native UI. Das funktioniert, falls Sie 20 Menschen und einen einzelnen Prozess haben. Aber der Moment Sie wollen zu:

Synchronisieren Sie Kandidaten zu Ihrem HR-System (BambooHR, Workday), das keine vorab-gebaute Integration hat
Ziehen Sie Reports in Ihren Data-Warehouse für Custom-Analytik
Bulk-importieren Sie Kandidaten von einem alten System
Bauen Sie ein Custom-Dashboard, das Ihr Team über die native UI bevorzugt
Automatisieren Sie Aufgaben mit Zapier oder Make.com ohne Code

...Sie benötigen eine öffentliche REST-API.

Eine REST-API ist die Lingua Franca von SaaS-Integration. Jedes Werkzeug, das HTTP spricht, kann mit es sprechen. Zapier, Make, n8n, Pipedream, Custom-Python-Skripte, Mobile-Apps, Ihre eigenem Dashboards – alle können mit einem einfachen Authentifizierungs-Token Daten lesen und schreiben.

Das Bearer-Token-Muster

Das einfachste sichere API-Muster ist Bearer-Tokens: Sie geben jedem Benutzer einen API-Schlüssel aus, sie enthalten ihn im Authorization: Bearer YOUR_KEY-Header, und jede Anfrage authentifiziert gegen den Schlüssel.

Das ist wie Stripe, GitHub, Slack, und die meisten modernen APIs funktionieren. Es ist leicht zu widerrufen (löschen Sie den Schlüssel), leicht zu rotieren (generieren Sie einen neuen), und leicht zu scopen (geben Sie verschiedene Schlüssel mit verschiedenen Berechtigungen aus).

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

Vergleichen Sie das zu Username/Passwort oder OAuth: Bearer-Tokens sind stateless (keine Sitzungs-Datenbank), können sofort invalidiert werden, und lässt Sie auditen, welcher Schlüssel welche Anfrage machte.

Scopes und Berechtigungen

Eine Sicherheits-Best-Practice: Nicht Tokens mit vollem Lesen-Schreiben Zugriff auf alles ausgeben. Stattdessen, nutze Scopes.

candidates:read       # Kann Kandidaten auflisten und sehen
candidates:write      # Kann Kandidaten bewegen, Notizen hinzufügen
tests:read            # Kann Test-Ergebnisse sehen
tests:write           # Kann Tests erstellen und bearbeiten
jobs:read             # Kann Jobs auflisten
webhooks:manage       # Kann Webhooks erstellen/löschen

Falls ein Dritt-Entwickler API-Zugriff anforder (sagen, ein HRIS-Provider, integrierend mit Ihrer Plattform), geben Sie ihnen einen Token mit nur candidates:read und candidates:write aus. Sie können Ihre Abrechnungs-Daten oder Interview-Fragen-Modifikation nicht sehen.

Scopes schützen auch gegen versehentlichen Schaden. Falls ein Integrations-Skript einen Bug hat und anfängt, Kandidaten zu löschen, erkennen Sie es schneller, falls das Skript nur candidates:read haben sollte.

Webhooks vs. Polling

Zwei Muster für Daten-Synchronizierung-Sicherung:

Webhooks (Event-getrieben):

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

Falls etwas in ClarityHire geschieht, postet es zu Ihrem Endpunkt. Sie verarbeiten sofort. Schnell, effizient, kein Polling-Overhead.

Polling (Pull-basiert):

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

Sie periodisch (jede 5 Minuten, jede Stunde) fragen ClarityHire "was änderte?" und verarbeiten die Antwort. Einfacher implementieren, falls Ihr System keinen HTTP-Endpunkt exponiert, aber langsamer und Lärmer.

Best-Practice: Webhooks für Echtzeit (Stufen-Wechsel, neue Bewerbungen), Polling für periodische Syncs (täglich Export aller Kandidaten zu Ihrem Data-Warehouse).

Beide Muster sollten Wiederversuches-Logik unterstützen. Webhooks können schlagen (Netzwerk-Ausfall, Ihren Endpunkt Ausfall). Die API sollte mit Exponential-Backoff erneut versuchen und lassen Sie fehlgeschlagene Versuche auf einem "Webhook-Logs"-Dashboard sehen.

Rate-Limits und Idempotenz

Wenn Sie eine API exponieren, Sie brauchen Schutzschienen gegen Missbrauch und versehentlichen Doppel.

Rate-Limits: "Sie können 1.000 Anfragen pro Stunde pro API-Schlüssel machen." Falls jemand überschreitet, bekommen Sie eine 429-Antwort mit einem Retry-After-Header. Zapier und andere Integrations-Plattformen respektieren diese Limits automatisch.

Idempotenz: Falls ein Webhook-Versand schlägt, wir versuchen es erneut. Aber was, falls die Anfrage tatsächlich erfolgreich war, aber die Antwort zeitausgelöst? Ohne Idempotenz, würden wir einen Doppel-Kandidaten erstellen oder den Kandidaten zweimal bewegen.

Lösung: Verlangen Sie einen Idempotency-Key-Header auf Schreib-Anfragen.

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

Die API speichert den Schlüssel und Antwort. Falls der gleiche Schlüssel erneut benutzt wird, gibt es die gecachte Antwort zurück. Keine Doppel.

Dokumentation und SDKs

Eine API ist ohne Docs nutzlos. Sie brauchen:

Endpunkt-Referenz: Jeder Route, jeder Parameter, jede Antwort-Format
Fehler-Codes: Was bedeutet ein 400? Ein 403?
Webhook-Event-Typen: Vollständige Liste von Events, die Sie ausmachen, mit Beispiel-Payloads
Code-Beispiele: curl, Python, JavaScript-Schnippets für häufige Aufgaben
Authentifizierung: Wie zu generieren und rotieren Schlüssel

Bonus: Veröffentlichen SDKs für populäre Sprachen (Python, JavaScript, Go). Zapier kommt mit einem eingebaut-SDK, aber Custom-Integrationen profitieren von einer nativen Kunde-Bibliothek, die Pagination, Wiederversuche, und Fehler-Handhabung handhabt.

Zapier-Integration: Nächste-Level-Leverage

Zapier verbindet hunderte Apps ohne Code. Einmal Sie exponieren eine REST-API, schreiben eine Zapier-Integration wird ein 1-2-Wochenprojekt statt ein 4-Wochenprojekt.

Beispiel Zap:

Trigger: "Neuer Kandidat in ClarityHire Job 'Senior Backend Engineer'"
Action 1: "Reihe zu Google-Sheets hinzufügen"
Action 2: "Slack-Nachricht versenden zu #hiring"
Action 3: "Kontakt in Pipedrive erstellen"

Ein Zapier-Benutzer stellt das ohne Code ein. Andere Zapier-Benutzer entdecken es im Zapier-Markt und adoptieren es. Sie haben 100-Integration Ökosystem gebaut ohne 100-Integrationen zu schreiben.

Wie ClarityHire seine API exponiert

ClarityHire bietet /api/v1/* mit Bearer-Token-Authentifizierung, Scoped-Berechtigungen, und Webhook-Support. Die Referenz-Docs leben auf api.clarityhire.com/docs. Rate-Limit: 1.000 Anfragen/Stunde pro Schlüssel. Idempotentes Schreiben mit Idempotency-Key-Header.

Beispiel-Endpunkte:

GET /api/v1/candidates – Kandidaten auflisten (unterstützt Filterung, Pagination)
GET /api/v1/candidates/{id} – Einzeln-Kandidat
POST /api/v1/candidates/{id}/move-stage – Stufen-Übergang
GET /api/v1/webhooks – Listen Sie Ihre aktiven Webhooks
POST /api/v1/webhooks – Registrieren Sie einen neuen Webhook

Webhooks können nach Event-Typ, job_id, oder Organisation gefiltert werden. Das System versucht gescheiterte Auslieferungen 10 mal über 24 Stunden mit Exponential-Backoff.

TL;DR

Eine öffentliche REST-API mit Bearer-Tokens entsperrt Integrationen. Scope-Berechtigungen von Use-Case. Bevorzuge Webhooks für Echtzeit-Sync, Polling für Batch-Exports. Erzwinge Idempotenz auf Schreib, um Doppel zu verhindern. Dokumentieren Sie gründlich, einschließlich Fehler-Codes und Beispiele. Zapier-Integration ist der Multiplizierer: Eine API ermöglicht tausend Use-Cases ohne Ihren Team Code-sie.

Die Investition in API-Design bezahlt sich im Dividenden von Flexibilität und Adoption.

apiintegrationszapierwebhooksrecruiting-automation