API Referenz

Einstieg in die API-Referenz

Überblick

Die talent Flow API ist eine REST-API über HTTPS. Alle Antworten sind JSON, alle Zugriffe laufen über OAuth 2.0 im Client-Credentials-Flow.

Basis-URL: https://api.talent360.io/v3 — alle Pfade in dieser Referenz verstehen sich relativ dazu.

Diese Seite erklärt, wie die Referenz aufgebaut ist und welche Konventionen für alle Endpunkte gelten. Wer stattdessen einen konkreten Anwendungsfall umsetzen will, ist im Integrationsguide besser aufgehoben — dort steht, welche Endpunkte in welcher Reihenfolge zusammenspielen.

Access Token anfordern, zwischenspeichern und richtig mitsenden.
Fertige Abläufe für ERP, eigenes Bewerbermanagement und BI-Werkzeuge.
Die vollständige Referenz mit Parametern, Schemas und Beispielen.

Wie die Referenz aufgebaut ist

Die Endpunkte sind nach fachlichen Bereichen gruppiert:

Bewerber

Bereich Inhalt
Bewerberübersichten Listen, Änderungen im Zeitraum, Dublettenprüfung per E-Mail
Bewerberdetails Stammdaten anlegen, ändern und löschen, Profil, Werdegang, Status, Arbeitsvertrag
Bewerberdokumente Lebenslauf und Zeugnisse hochladen, Dokumentänderungen abrufen
Bewerberkommunikation Kommunikationseinträge und deren Anhänge
Candidates Kurzprofil, Status- und Kontakthistorie, Bewerbung anlegen
Bewerbungen Bewerbung auf eine Stellenanzeige übertragen

Firmen

Bereich Inhalt
Firmenübersichten Firmenänderungen im Zeitraum, pro Tag und pro Stunde
Firmendetails Firma anlegen und ändern, Kunden- und Vertragsstatus, Berufe
Betriebsstätten Betriebsstätten lesen, anlegen und ändern
Einsatzorte Einsatzorte lesen und anlegen
Firmenkontakte Ansprechpartner lesen, anlegen und ändern

Anfragen

Bereich Inhalt
Anfragendetails Anfragen für Arbeitnehmerüberlassung, Direktvermittlung und Dienstleistungsvertrag; Statuswechsel
Anfragenauswertungen Anfragen-Report

Stellenanzeigen

Bereich Inhalt
Stellenanzeigenübersichten Anzeigen auflisten, Änderungen im Zeitraum
Stellenanzeigendetails Eine Anzeige im Detail
Stellenanzeigenauswertungen Organische und Performance-Statistiken, Monatsbericht

Stammdaten und Verwaltung

Bereich Inhalt
talent.Flow Stammdaten Anreden, Länder, Sprachen, Nationalitäten, Arbeitszeitmodelle und weitere Wertelisten
Benutzer Benutzer und Zuständigkeiten
Niederlassungen Niederlassungen des Mandanten
Webhooks Ereignistypen, Registrierung, Einstellungen, Protokoll

Konventionen, die überall gelten

Pflicht-Header

Header Wert Erforderlich
Authorization Bearer Immer
User-Agent Gültiger User-Agent mit Kundenname Immer
Content-Type application/json Bei POST und PUT
Accept application/json Empfohlen

Details dazu auf der Seite Authentifizierung.

Zwei Antwortformate

Nicht alle Endpunkte antworten gleich. Ein Teil liefert das Ergebnis direkt, ein anderer verpackt es in einen Umschlag. Wer beide in dieselbe Verarbeitung hängt, braucht zwei Auswertungspfade.

Direkt — das Ergebnis ist die Antwort:

{ "id": 4711, "name": "Musterfirma" }

Umschlag — die Nutzdaten liegen unter data:

{
  "isFaulty": false,
  "data": [ … ],
  "message": null,
  "validationErrors": [],
  "serviceAlerts": [],
  "statusCode": 200,
  "messageGuid": "…"
}

Beim Umschlag zuerst isFaulty prüfen, dann data auswerten. Welche Form ein Endpunkt liefert, steht bei jedem Endpunkt am Response-Schema.

Fehlerformat

Fehlerantworten sind einheitlich aufgebaut:

{
  "messageGuid": "3f8b1c2e-…",
  "message": "Beschreibung des Fehlers",
  "validationErrors": []
}
Status Bedeutung
400 Ungültige Anfrage oder Validierungsfehler — Details in validationErrors
401 Kein oder ungültiger Access Token
403 Token gültig, aber für diese Ressource nicht berechtigt
404 Datensatz nicht gefunden

Protokollieren Sie messageGuid mit. Bei einer Supportanfrage lässt sich der Vorgang darüber eindeutig zuordnen — ohne diese Kennung bleibt nur die Suche über Zeitstempel.

Datums- und Zeitangaben

  • Query-Parameter für Zeiträume erwarten das Format YYYY-MM-DD, zum Beispiel startDate=2026-07-01.

  • Zeitstempel in Antworten enden auf AtUtc und sind immer UTC — etwa createdAtUtc, modifiedAtUtc, importedAtUtc.

Kein Paging

Die Listen- und Export-Endpunkte kennen weder skip noch take. Grenzen Sie große Abfragen stattdessen über Zeiträume ein — etwa monatsweise über startDate und endDate.

Löschen

DELETE-Endpunkte gibt es nur für vier Unterobjekte eines Bewerbers:

Objekt Endpunkt
Führerschein DELETE /v3/candidates/{candidateId}/driverslicences/{driversLicenseId}
Sprache DELETE /v3/candidates/{candidateId}/languages/{languageId}
Beruf DELETE /v3/candidates/{id}/professions/{professionId}
Qualifikation DELETE /v3/candidates/{id}/qualifications/{qualificationId}

Für alles andere — den Bewerber selbst, dessen Kontaktwege, Werdegang, Keywords und Dokumente sowie den gesamten Firmenbereich — gibt es keinen Löschendpunkt. Dort führt der Weg über den Statuswechsel.

Zuordnung zu einem Fremdsystem

Firmen und Betriebsstätten tragen die Felder importExternalId und importedAtUtc. importExternalId ist beim Anlegen schreibbar und beim Lesen sichtbar — dort kann ein anbindendes System seine eigene Id ablegen, statt über den Namen zu matchen.

Bewerber haben dieses Feld nicht. Für sie braucht ein anbindendes System eine eigene Zuordnungstabelle.

Nächste Schritte

Token anfordern und mit einem lesenden Stammdaten-Endpunkt testen.
Fertige Abläufe für ERP, eigenes Bewerbermanagement und Auswertungen.