talent Flow Api | V3 API Reference

Kundenanfragen — von der Anlage über den Statusverlauf bis zur Auswertung.

Drei Anfragearten mit je eigenem Anlage-Endpunkt und eigenem Datenmodell: Arbeitnehmerüberlassung, Direktvermittlung und Dienstleistungsvertrag.

Anfragen anlegen, lesen und im Status weiterschalten.

Jede Anfrageart hat einen eigenen Anlage-Endpunkt mit eigenem Datenmodell: Arbeitnehmerüberlassung, Direktvermittlung und Dienstleistungsvertrag. Der Statuswechsel ist für alle drei derselbe Endpunkt.

Kennzahlen zu Anfragen über einen Zeitraum.

Ergänzt die Stellenanzeigenauswertungen um die Vertriebsseite: nicht „wie liefen die Anzeigen", sondern „wie entwickelten sich die Anfragen der Kunden".

Alles rund um Bewerber — Bestandsabgleich, Stammdaten, Dokumente und Kommunikation.

Für eine neue Anbindung ist die Reihenfolge meist dieselbe: Bewerberübersichten für den Abgleich, Bewerberdetails für die laufende Pflege, Bewerberdokumente für Unterlagen.

Listen und Änderungsströme über den gesamten Bewerberbestand. Hier beginnt jede Anbindung: einmalig der Vollabzug über die Export-Endpunkte, danach ausschließlich Deltas über die Änderungsendpunkte. Enthält außerdem die Dublettenprüfung per E-Mail-Adresse.

Die Änderungsantwort ist bereits nach new, modified und deleted getrennt. Die deleted-Liste ist der einzige Weg, von gelöschten Bewerbern zu erfahren — es gibt keinen Löschendpunkt für Bewerber.

Beachten Sie: Diese Endpunkte kennen kein Paging. Grenzen Sie große Abfragen über Zeiträume ein.

Alles, was an einem einzelnen Bewerber hängt: Stammdaten anlegen und ändern, Kontaktwege, Profil, Werdegang, Status und Arbeitsvertrag.

Zwei Dinge, die man kennen sollte:

• PUT /candidates/{candidateId} ist ein Teil-Update — es werden nur die übermittelten Felder geändert. Sie müssen den Datensatz nicht vollständig zurückschicken.
• Die vier DELETE-Endpunkte dieses Bereichs (Führerschein, Sprache, Beruf, Qualifikation) sind die einzigen Löschendpunkte der gesamten API.

Ein über POST /candidates angelegter Bewerber wird in talent.Flow erst sichtbar, wenn zu ihm mindestens eine Bewerbung existiert.

Lebenslauf, Zeugnisse und sonstige Unterlagen eines Bewerbers hochladen und abrufen.

Dokumente haben einen eigenen Änderungsstrom. Ein Bewerber kann unverändert bleiben, während ein Dokument dazukommt — wer nur den Bewerberstrom abfragt, verpasst neue Lebensläufe und Zeugnisse. Fragen Sie beide Ströme ab, wenn Sie Dokumente spiegeln.

Kommunikationseinträge zu einem Bewerber anlegen und mit Anhängen versehen.

Gedacht für Systeme, die eigene Korrespondenz führen — etwa ein Mailsystem oder ein Messenger — und diese in talent.Flow sichtbar machen wollen, damit die Historie am Bewerber vollständig bleibt.

Übertragung einer Bewerbung auf eine Stellenanzeige aus einem Fremdsystem — etwa einer eigenen Karriereseite oder einem Jobportal.

Wichtig für jede Anbindung, die Bewerber anlegt: Ein Bewerber ohne mindestens eine Bewerbung wird in talent.Flow nicht angezeigt. Legen Sie deshalb Bewerber und Bewerbung im selben Vorgang an.

Kundenfirmen mit ihren Betriebsstätten, Einsatzorten und Ansprechpartnern.

Zum Lesen genügt ein einziger Aufruf: GET /customers/{id} liefert den ganzen Baum verschachtelt. Die Unterbereiche brauchen Sie zum Anlegen und Ändern — und für gezielte Nachladungen nach einem Webhook-Ereignis.

Beim Anlegen ist die Reihenfolge vorgegeben: erst Firma, dann Betriebsstätte, dann Einsatzort.

Änderungsströme über den Firmenbestand — nach Zeitraum, pro Tag oder pro Stunde.

Für den laufenden Abgleich sind Webhooks der bessere Weg: sie melden früher und mit weniger Aufrufen. Diese Endpunkte sind für den Erstabgleich gedacht und für die Wiederherstellung nach einer Störung.

Firmen anlegen, ändern und lesen — samt Kunden- und Vertragsstatus.

GET /customers/{id} liefert die Firma vollständig verschachtelt: Betriebsstätten, deren Einsatzorte und die Ansprechpartner in einem einzigen Aufruf. Sie müssen die Unterobjekte nicht einzeln nachladen.

Das Feld importExternalId nimmt die Id Ihres Quellsystems auf — beim Anlegen schreibbar, beim Lesen sichtbar. Damit brauchen Sie keine eigene Zuordnungstabelle und kein Matching über den Firmennamen.

Löschen ist im Firmenbereich nicht vorgesehen; der Weg führt über den Statuswechsel.

Betriebsstätten einer Firma lesen, anlegen und ändern.

Jede Betriebsstätte trägt eigene Kontaktdaten, Kostenstelle und USt-IdNr. sowie eine eigene importExternalId für die Zuordnung zu Ihrem System. Die zugeordneten Einsatzorte hängen darunter und kommen beim Lesen der Firma bereits mit.

Einsatzorte lesen und anlegen.

Ein Einsatzort hängt immer an einer Betriebsstätte. Die Reihenfolge beim Anlegen ist damit vorgegeben: erst Firma, dann Betriebsstätte, dann Einsatzort.

Einen Änderungsendpunkt gibt es nicht — eine Korrektur bedeutet in der Praxis, einen neuen Einsatzort anzulegen und den alten fachlich außer Betrieb zu nehmen.

Ansprechpartner einer Firma lesen, anlegen und ändern.

Beim Lesen der Firma sind die Kontakte bereits enthalten. Die Einzelabrufe hier brauchen Sie vor allem für gezielte Nachladungen, etwa nachdem ein Webhook einen neu hinzugefügten Ansprechpartner gemeldet hat.

Stellenanzeigen und ihre Kennzahlen.

Die Übersichten und Details liefern die Stammdaten einer Anzeige, die Auswertungen die Leistungsdaten: Klicks, Bewerbungen und — in der Performance-Variante — Kosten, je Tag und Kanal.

Für Excel und BI-Werkzeuge ist der Monatsbericht unter den Auswertungen der richtige Einstieg.

Stellenanzeigen auflisten und Änderungen im Zeitraum abrufen.

Liefert die Stammdaten zu den Kennzahlen aus den Stellenanzeigenauswertungen — Titel, Laufzeit und Zuordnung, die eine reine Kennzahlenzeile nicht enthält.

Eine einzelne Stellenanzeige mit allen Feldern.

Nutzen Sie diesen Endpunkt, wenn Sie aus einer Übersicht oder einer Kennzahlenzeile heraus die vollständigen Angaben zu einer Anzeige brauchen.

Kennzahlen zu Anzeigen und Kampagnen — je Tag und je Kanal aufgeschlüsselt.

Zwei Statistikarten, die sich in genau einer Kennzahl unterscheiden: die organische Statistik führt Klicks und Bewerbungen, die Performance-Statistik zusätzlich die Kosten.

Der ergiebigste Einstieg ist GET /reports/performance/jobs — der Monatsbericht über alle Anzeigen. Er liefert trotz des Namens tagesgenaue Zeilen und enthält zusätzlich Kampagnennamen und Schlagworte.

Achtung beim Auswerten: Die Statistik-Endpunkte antworten mit einem Umschlag (Nutzdaten unter data), der Monatsbericht dagegen mit einem nackten Array.

Organisatorische Grunddaten Ihres Mandanten: Benutzer und ihre Zuständigkeiten sowie die Niederlassungen.

Die fachlichen Wertelisten — Anreden, Länder, Sprachen, Nationalitäten und weitere — stehen separat unter talent.Flow Stammdaten.

Die Benutzer des Mandanten und ihre Zuständigkeiten.

Gebraucht überall dort, wo ein Datensatz einer verantwortlichen Person zugeordnet werden soll — etwa beim Anlegen einer Firma oder eines Bewerbers über das Feld responsibility.

Die Niederlassungen des Mandanten.

Ihre Ids dienen in mehreren Änderungsendpunkten als Filter (officeId) — etwa um den Bewerberabgleich auf eine einzelne Niederlassung einzugrenzen.

Nicht zu verwechseln mit den Betriebsstätten: Niederlassungen gehören zu Ihnen, Betriebsstätten zu Ihren Kundenfirmen.

Wertelisten, die in anderen Endpunkten als Id referenziert werden: Anreden, Länder, Bundesländer, Sprachen, Nationalitäten, Familienstände, Arbeitszeitmodelle, Mobilitäts- und Behinderungsarten, Bonusarten, Zeiteinheiten und Bezugsquellen.

Diese Listen ändern sich selten. Cachen Sie sie, statt sie bei jedem Vorgang abzurufen — ein täglicher Abgleich genügt.

Ein lesender Stammdaten-Endpunkt eignet sich außerdem gut als Smoke-Test für eine frisch eingerichtete Anbindung, weil er keine Daten verändert.

Registrierung und Verwaltung von Webhooks: verfügbare Ereignistypen lesen, Endpunkte an- und abmelden, das Datenformat setzen und das Zustellprotokoll abrufen.

Ein Webhook liefert keine Nutzdaten, sondern eine Referenz auf den Datensatz — entityId samt Abruf-Endpunkt. Den eigentlichen Abruf macht Ihr System selbst.

Zwei Dinge sind für den Betrieb entscheidend:

• Antworten Sie sofort mit 200. Nach 10 fehlgeschlagenen Zustellungen wird die Registrierung pausiert.
• Auch dann gehen keine Ereignisse verloren: sie werden weiter protokolliert und lassen sich über den Protokoll-Endpunkt nachträglich abrufen.

Wie das im Zusammenspiel aussieht, zeigt der Integrationsguide.