Integrationsguide: Einstieg

Überblick

Der Integrationsguide beschreibt komplette Abläufe statt einzelner Endpunkte: welche Aufrufe in welcher Reihenfolge zusammenspielen, was vorher da sein muss, und woran Integrationen in der Praxis scheitern.

Wenn Sie einen bestimmten Endpunkt suchen, ist die API-Referenz der richtige Ort. Diese Seiten hier beantworten stattdessen die Frage: „Wie setze ich diesen Anwendungsfall um?"

Welcher Weg passt zu Ihrem System?

Ihr System	Was Sie tun wollen	Seite
ERP oder Lohnsystem	Eingestellte Bewerber übernehmen und dort weiterpflegen	ERP-Integration: Bewerberablauf
ERP oder Lohnsystem	Firmen mit Betriebsstätten und Ansprechpartnern übernehmen	ERP-Integration: Firmenablauf
Eigenes Bewerbermanagement	Bewerberbestand aufbauen und aktuell halten	Bewerber in ein eigenes System übernehmen
Excel, Power BI, Tableau	Kennzahlen zu Anzeigen und Kampagnen auswerten	Auswertungen zu Stellenanzeigen und Kampagnen

Vom Webhook „Candidate marked as hired" bis zur laufenden Pflege im ERP.

Firma mit Betriebsstätten, Einsatzorten und Kontakten in einem Aufruf.

Erstbefüllung und Delta-Abgleich für ein eigenes Bewerbermanagement.

Kampagnen-Kennzahlen für Excel und BI-Werkzeuge, rein lesend.

Zwei Muster — und wann welches

Alle vier Abläufe bauen auf einem von zwei Mustern auf.

Push: talent.Flow meldet sich

talent.Flow ruft Ihren Endpunkt auf, sobald ein Ereignis eintritt. Der Aufruf enthält keine Nutzdaten, sondern eine Referenz: die entityId und den Endpunkt, über den der Datensatz abzurufen ist.

sequenceDiagram
    participant TF as talent.Flow
    participant Sys as Ihr System
    TF->>Sys: POST auf Ihre Webhook-URL (Ereignis + entityId)
    Sys-->>TF: 200 OK
    Sys->>TF: GET auf den mitgelieferten Endpunkt
    TF-->>Sys: Datensatz

Passt, wenn Ihr System zeitnah auf Änderungen reagieren soll — Übernahme in ein ERP, Anstoßen eines Folgeprozesses.

Pull: Sie fragen nach

Ihr System ruft in einem festen Takt die Änderungen eines Zeitraums ab und verarbeitet sie im Block.

Passt, wenn Sie einen Bestand spiegeln oder auswerten wollen — eigenes Bewerbermanagement, BI, Reporting.

Nicht beides gleichzeitig für denselben Zweck. Wer Webhooks abonniert und zusätzlich im Minutentakt die Änderungsendpunkte pollt, erzeugt doppelte Verarbeitung und unnötige Last. Die Änderungsendpunkte sind neben dem Pull-Muster vor allem für den Erstabgleich und für die Wiederherstellung nach einer Störung gedacht.

Was für jede Integration gilt

Authentifizierung

Ein Access Token pro Tag, nicht pro Aufruf. Das Freikontingent liegt bei 100 Tokens pro Monat — eine Implementierung, die pro Request einen neuen Token zieht, überschreitet es innerhalb von Minuten. Details auf der Seite Authentifizierung.

User-Agent

Jeder Request braucht einen gültigen User-Agent mit Ihrem Kundennamen. Viele HTTP-Bibliotheken und besonders BI-Konnektoren senden von sich aus keinen — er muss explizit gesetzt werden.

Reihenfolgen, die Sie nicht umgehen können

Regel	Warum
Firma → Betriebsstätte → Einsatzort	Ein Einsatzort hängt immer an einer Betriebsstätte
Bewerber → Bewerbung	Ein Bewerber ohne mindestens eine Bewerbung wird in talent.Flow nicht angezeigt

Löschen ist die Ausnahme, nicht die Regel

DELETE-Endpunkte gibt es nur für vier Unterobjekte eines Bewerbers — Führerschein, Sprache, Beruf und Qualifikation. Für den Bewerber selbst, für dessen Kontaktwege, Werdegang, Keywords und Dokumente sowie für den gesamten Firmenbereich existiert kein Löschendpunkt. Planen Sie Ihre Integration so, dass Löschen dort nicht Teil des Regelbetriebs ist — der vorgesehene Weg ist der Statuswechsel.

Umgekehrt gilt für den Abgleich in Ihre Richtung: Löschungen erfahren Sie über die deleted-Liste der Änderungsendpunkte. Wer sie ignoriert, sammelt Datensätze an, die es nicht mehr geben darf.

Datensätze wiederfinden

Objekt	Zuordnung zum Fremdsystem
Firma, Betriebsstätte	Feld `importExternalId` — beim Anlegen schreibbar, beim Lesen sichtbar
Bewerber	Kein Feld vorhanden — eigene Zuordnungstabelle nötig

Bevor Sie anfangen

Zugangsdaten (ClientId und ClientSecret) liegen vor und werden serverseitig gehalten.
Der Token wird zwischengespeichert und auf Basis von expires_in erneuert.
Ein User-Agent mit Kundenname ist gesetzt.
Entschieden ist, ob Ihr Anwendungsfall dem Push- oder dem Pull-Muster folgt.
Für Bewerber ist eine Zuordnungstabelle vorgesehen, für Firmen die Nutzung von importExternalId.
Der Umgang mit Löschungen ist geklärt — in beide Richtungen.

Datenschutz: Bewerberdaten sind besonders schützenswerte personenbezogene Daten im Sinne der DSGVO. Übertragung, Speicherung und Löschung in Ihrem System müssen entsprechend abgesichert sein. Übernehmen Sie nur die Felder, die Sie fachlich benötigen.