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, Konzernkatalog
Betriebsstätten Betriebsstätten lesen, anlegen, ändern und löschen
Einsatzorte Einsatzorte lesen, anlegen, ändern und löschen
Firmenkontakte Ansprechpartner lesen, anlegen, ändern und löschen

Anfragen

Bereich Inhalt
Anfragendetails Anfragen für Arbeitnehmerüberlassung, Direktvermittlung und Dienstleistungsvertrag; Statuswechsel, Umhängen und Löschen
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, Schichten, Vertragslaufzeiten, Arbeitsorte, Währungen 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 — auch für einen gelöschten Datensatz

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 für fünf Unterobjekte eines Bewerbers und, seit Version 3.4.0, für vier Objekte im Firmenbereich. Gelöscht wird immer als Soft-Delete, genau wie in talent.Flow: Der Datensatz wird deaktiviert und liefert im Einzelabruf anschließend 404.

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}
Schlagwort (Neu in V 3.4.0) DELETE /v3/candidates/{candidateId}/keywords/{keywordId}
Betriebsstätte (Neu in V 3.4.0) DELETE /v3/customers/{customerId}/offices/{officeId}
Einsatzort (Neu in V 3.4.0) DELETE /v3/customers/{customerId}/offices/{officeId}/locations/{locationId}
Ansprechpartner (Neu in V 3.4.0) DELETE /v3/customers/{customerId}/contacts/{contactId}
Anfrage (Neu in V 3.4.0) DELETE /v3/customers/{customerId}/requests/{requestId}

Für den Bewerber selbst, dessen Kontaktwege, Werdegang und Dokumente sowie für die Firma selbst gibt es keinen Löschendpunkt. Dort führt der Weg über den Statuswechsel.

Zuordnung zu einem Fremdsystem

Firmen, Betriebsstätten, Einsatzorte und Ansprechpartner 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. Neu in V 3.4.0: Auch an Einsatzorten werden beide Felder beim Lesen geliefert.

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.