Die Bullhorn API ist die Schnittstelle, über die sich Bullhorn mit externen Systemen verbinden und individuell erweitern lässt. Sie ermöglicht direkten Zugriff auf Kandidaten, Jobs, Kunden, Notizen und Zeiterfassungsdaten, den Aufbau eigener Frontends und tiefgreifende Automatisierungen. Wer Bullhorn über den Standard hinaus nutzen will, kommt an ihr nicht vorbei.
Dieser Beitrag erklärt, wie die Authentifizierung funktioniert, welche Endpoints es gibt, wo die typischen Fallstricke liegen und wie sich häufige Integrationsszenarien in der Praxis lösen lassen.
Was ist die Bullhorn REST API?
Die Bullhorn REST API ist eine Schnittstelle, über die Entwickler auf alle relevanten Daten in Bullhorn zugreifen und diese bearbeiten können. Sie folgt dem REST-Standard und gibt Daten im JSON-Format zurück, was die Anbindung an nahezu jede bestehende Systemlandschaft ermöglicht. Die offizielle Dokumentation und die vollständige API Reference sind auf bullhorn.github.io hinterlegt, inklusive aller Endpoints, Parameter und Beispiele.
Authentifizierung — der zweistufige Login
Hier liegt die erste Besonderheit, die viele Integrationen zu Beginn unterschätzen. Der API-Zugang läuft nicht über den normalen Benutzer-Login auf app.bullhornstaffing.com, sondern über einen eigenen, zweistufigen Prozess.
Bullhorn nutzt OAuth 2.0, aber anders als bei vielen anderen APIs authentifiziert der Access Token allein noch keine Datenabfragen. Der Ablauf hat zwei Schritte:
Zuerst fordert man mit Client ID und Client Secret über den OAuth-Flow einen Access Token an. Dieser Access Token wird dann in einem zweiten Login-Call gegen einen BhRestToken getauscht. Erst dieser BhRestToken, ein session-spezifisches Token, authentifiziert die eigentlichen API-Aufrufe. Der BhRestToken hat eine begrenzte Gültigkeit und läuft nach einer konfigurierbaren Leerlaufzeit ab, weshalb eine automatische Token-Erneuerung von Anfang an eingeplant werden sollte.
Wer diesen zweiten Schritt übersieht und versucht, direkt mit dem Access Token abzufragen, bekommt keine Daten, sondern Authentifizierungsfehler. Das ist der häufigste Stolperstein beim Einstieg.
Die dynamische Base-URL — nicht hardcoden
Die zweite Besonderheit, die produktive Integrationen stabil oder fragil macht: Bullhorn gibt beim Login eine datacenterspezifische Base-URL zurück, etwa in der Form rest-{datacenter}.bullhornstaffing.com/rest-services. Für europäische Kunden ist das häufig das EMEA-Datacenter.
Diese restUrl darf niemals fest im Code verankert werden. Sie wird bei jedem Login dynamisch aus der Login-Antwort ausgelesen. Wer die URL hardcodet, riskiert, dass die Integration bricht, sobald Bullhorn den Account auf ein anderes Datacenter verschiebt oder eine andere Instanz zuweist. Der korrekte Weg führt über einen loginInfo-Aufruf, der die gültigen URLs für den jeweiligen Account zurückgibt.
API-Zugang einrichten — Schritt für Schritt
Der Zugang wird bei Bullhorn oder über einen Implementierungspartner beantragt. Der typische Ablauf:
Zunächst beantragt man den API-Zugang und erhält die Credentials, bestehend aus Client ID und Client Secret. Anschließend durchläuft man den OAuth-Flow und generiert den Access Token, der im Login-Call gegen den BhRestToken getauscht wird. Danach empfiehlt sich ein Verbindungstest mit Postman, für den auf GitHub fertige Beispiel-Collections bereitstehen. Steht die Verbindung, lässt sich die erste Abfrage absetzen und Daten abrufen.
Endpoints im Überblick
Die vollständige Entity Reference mit allen Endpoints und Beispielen liegt auf bullhorn.github.io. Die wichtigsten Bereiche für Personaldienstleister:
Kandidaten — Über die Candidate-Endpoints lassen sich Kandidatendaten abrufen, anlegen, aktualisieren und löschen: alle Kandidaten mit einem bestimmten Status laden, ein Profil anhand der ID abrufen oder neue Kandidaten programmatisch anlegen.
Jobs — Offene Stellen abrufen und verwalten, von der Auflistung aller aktiven Jobs bis zur automatischen Synchronisierung mit externen Jobportalen.
Kunden und Kontakte (CRM) — Zugriff auf Kundenunternehmen, Ansprechpartner und Deal-Tracking, etwa um CRM-Daten in externe Systeme zu synchronisieren.
Bewerbermanagement (ATS) — Bewerbungen, Pipeline-Status und Placement-Daten programmatisch verwalten, ideal für eigene Dashboards oder automatisierte Prozesse.
Daten filtern — /search und /query richtig einsetzen
Ein Punkt, der in der Praxis regelmäßig zu unerwarteten Ergebnissen führt: Bullhorn bietet zwei unterschiedliche Wege, Daten abzufragen, und sie sind nicht austauschbar.
Der /search-Endpoint nutzt Lucene-Syntax, der /query-Endpoint arbeitet mit einer SQL-artigen WHERE-Klausel. Wer die Syntax des einen auf dem anderen Endpoint verwendet, bekommt keine Fehlermeldung, sondern schlicht falsche oder leere Ergebnisse. Zu wissen, welcher Endpoint für welchen Anwendungsfall der richtige ist, spart erhebliche Debugging-Zeit.
Ein weiterer Fallstrick: Der fields-Parameter ist auf allen Entity- und Such-Endpoints Pflicht. Lässt man ihn weg, gibt die API kommentarlos nur das id-Feld zurück, ohne Fehler. Wer unvollständige Datensätze bekommt, sollte hier zuerst prüfen.
Rate Limits — was einzuplanen ist
Die Bullhorn API ist nicht unbegrenzt nutzbar. Rate Limits legen fest, wie viele Anfragen pro Zeiteinheit erlaubt sind. Die genauen Grenzen hängen vom Vertrag ab und sind nicht öffentlich einheitlich dokumentiert. Erschwerend kommt hinzu, dass Bullhorn keine Retry-After-Header sendet, an denen sich eine Wartezeit ablesen ließe. Die Retry-Logik muss also konservativ selbst implementiert werden. Wer größere Datenmengen synchronisiert, sollte Batching und Caching von Anfang an einplanen, um Limits gar nicht erst zu erreichen.
Webhooks und Events — die Subscription-API
Neben dem klassischen Request-Response-Modell bietet Bullhorn eine Event-Subscription. Damit lassen sich Änderungen abonnieren, statt aktiv abzufragen, was unnötige Anfragen spart und die Rate Limits schont.
Wichtig zu wissen: Die Events-API ist poll-basiert, nicht push-basiert. Bullhorn schickt die Events nicht aktiv an euren Endpoint, sondern hält sie zum Abholen bereit. Wer die Subscription nicht innerhalb des Aufbewahrungsfensters abfragt, verliert Events. Die genaue Aufbewahrungsdauer sollte mit dem Bullhorn Support abgeklärt werden, bevor eine Integration darauf aufbaut.
Typische Integrationsszenarien
Die REST API ist flexibel genug für eine Vielzahl von Einsätzen. Die häufigsten Szenarien bei Personaldienstleistern:
ERP-Integration — Werden Kandidaten- oder Auftragsdaten parallel in Bullhorn und einem externen ERP gepflegt, entsteht manuelle Doppelpflege. Ein automatischer Datenabgleich über die API überträgt Änderungen in beide Richtungen und macht die Doppelerfassung überflüssig.
Individuelle Kandidaten-Portale — Wenn das Standard-Interface nicht zu Branding oder Prozess passt, lässt sich ein eigenes Frontend aufbauen, das Bullhorn als Datenbasis im Hintergrund nutzt, aber vollständig im eigenen Design läuft.
Automatisiertes Reporting — Statt Management-Berichte manuell aus Bullhorn zu exportieren und in Excel aufzubereiten, lassen sich die Daten direkt abrufen und in einem eigenen Dashboard in Echtzeit darstellen.
Zeiterfassung und Lohnbuchhaltung — Sind Zeiterfassungs- und Abrechnungssysteme nicht mit Bullhorn verbunden, lässt sich die Übertragung automatisieren, sodass Zeiten und Abrechnungsdaten zwischen den Systemen fließen.
Salesforce-Anbindung — Werden Bullhorn und Salesforce parallel genutzt, lassen sich Kundendaten, Deals und Kontakte über die native Integration synchron halten.
Häufige API-Fehler und ihre Ursachen
Wer mit der Bullhorn REST API arbeitet, begegnet früher oder später denselben Fehlermeldungen:
401 Unauthorized — Der BhRestToken ist abgelaufen oder ungültig. Token über den Login-Call neu generieren; eine automatische Erneuerung einplanen.
404 Not Found — Der angeforderte Endpoint oder Datensatz existiert nicht. Prüfen, ob die Entity-ID korrekt und der Endpoint in der genutzten Bullhorn-Version verfügbar ist.
429 Too Many Requests — Das Rate Limit wurde überschritten. Anfragen drosseln, Batching und Caching einsetzen.
500 Internal Server Error — Serverseitiger Fehler bei Bullhorn, in der Regel temporär. Kurz warten und wiederholen; hält der Fehler an, den Support kontaktieren.
Versioning und Testumgebung
Bullhorn entwickelt die REST API kontinuierlich weiter und kommuniziert Breaking Changes in der Regel vorab. Für produktive Integrationen empfiehlt sich ein regelmäßiger Blick in die offizielle Dokumentation, um sicherzustellen, dass bestehende Anbindungen stabil laufen. Grundregel: API-Updates immer in einer separaten Umgebung testen, bevor sie produktiv gehen.
Für solche Tests bietet Bullhorn auf Anfrage Sandbox-Zugänge, eine vom Live-System isolierte Umgebung, in der Änderungen keine echten Kandidaten- oder Kundendaten berühren. Den Zugang beantragt man direkt bei Bullhorn oder über einen Implementierungspartner.
Häufige Fragen zur Bullhorn API (FAQ)
Was ist die Bullhorn REST API?
Die Bullhorn REST API ist eine Programmierschnittstelle, die direkten Zugriff auf alle Daten in Bullhorn ermöglicht: Kandidaten, Jobs, Kunden, Zeiterfassung und mehr. Sie folgt dem REST-Standard und gibt Daten im JSON-Format zurück.
Wie funktioniert die Authentifizierung?
Bullhorn nutzt OAuth 2.0 mit einem zweiten Schritt: Der über OAuth erhaltene Access Token wird in einem Login-Call gegen einen session-spezifischen BhRestToken getauscht, der die eigentlichen API-Aufrufe authentifiziert. Der BhRestToken läuft nach einer konfigurierbaren Leerlaufzeit ab.
Wie bekomme ich Zugang zur API?
Der Zugang wird über Bullhorn oder einen Implementierungspartner beantragt. Man erhält Client ID und Client Secret, mit denen die OAuth-Authentifizierung durchlaufen wird.
Was ist bei den Rate Limits zu beachten?
Die Limits hängen vom Vertrag ab und sind nicht öffentlich einheitlich dokumentiert. Da Bullhorn keine Retry-After-Header sendet, muss die Retry-Logik konservativ selbst implementiert werden. Batching und Caching helfen, Limits zu vermeiden.
Worin unterscheiden sich /search und /query?
Der /search-Endpoint nutzt Lucene-Syntax, /query arbeitet mit einer SQL-artigen WHERE-Klausel. Die beiden sind nicht austauschbar; die falsche Syntax auf dem falschen Endpoint liefert unerwartete Ergebnisse.
Kann ich die API mit Postman testen?
Ja. Auf GitHub stehen fertige Postman-Collections bereit, die den Einstieg in Authentifizierung und erste Abfragen erleichtern.
Bullhorn API-Integration — wir unterstützen euch
Die REST API bietet enorme Möglichkeiten, aber die saubere Einrichtung und individuelle Entwicklung braucht Erfahrung, gerade bei der Authentifizierung, dem Datacenter-Handling und der Vermeidung von Rate-Limit-Problemen. Schweizer Solutions unterstützt euch bei der API-Integration, dem Aufbau eigener Schnittstellen und der Anbindung externer Systeme wie ERP, Zeiterfassung und Lohnbuchhaltung.