Firmendetails

Konzerne lesen

GET /customers/corporations

Neu in V 3.4.0: Liefert die aktiven Konzerne (Unternehmensgruppen) des Accounts mit Id, Name und externer Id. Die hier gelieferten Ids sind die zulässigen Werte für corporationId an POST /customers und PUT /customers/{customerId}.

Der Katalog liegt bewusst nicht unter /masterdata: Konzerne sind Kundenstammdaten des Accounts, keine systemweit geteilten Stammdaten. Die Antwort trägt zusätzlich die einheitliche Form values, die alle Katalog-Endpunkte verwenden.

Neue Konzerne legt die Public API nicht an; das bleibt Stammdatenpflege in der Oberfläche.

Responses

200 — OK

400 — Ungültige Anfrage oder Validierungsfehler

Firmendetails lesen

GET /customers/{id}

Dieser Endpunkt gibt eine spezifische Firma zurück.

Neu in V 3.4.0:

• notes und ranking werden gelesen. Bisher ließen sich beide Felder nur über POST /customers schreiben, aber nicht auslesen.
• corporationId und corporation liefern den zugeordneten Konzern (Id und Name). Gültige Werte für corporationId liefert GET /customers/corporations.
• contacts[].linkedInUrl und contacts[].xingUrl werden vollständig mit Host geliefert (https://www.linkedin.com/…, https://www.xing.com/…), ohne Wert null, dasselbe Format wie an GET /customers/contacts/{contactId}. Bisher stand hier nur der gespeicherte Profilpfad.
• Der Aufruf ohne Token liefert 401. Bisher endete er in einem 500.

Parameters

Responses

200 — OK

404 — Firma nicht gefunden

Firma anlegen

POST /customers

Legt eine Firma an und liefert deren Id zurück.

Pflichtfelder sind name, companyTypeId und responsibility (mit userId und officeId). Fehlt eines davon, antwortet die API mit 400 und einem Validierungsfehler auf dem jeweiligen Feld.

companyTypeId ist die Rechtsform und wird oft übersehen, weil sie in Quellsystemen häufig Teil des Firmennamens ist. Gültige Werte liefert GET /masterdata/CompanyTypes; für „keine Angabe" ist 130 (Unknown) vorgesehen. Beim PUT /customers/{customerId} und an der Betriebsstätte ist das Feld optional.

Adresszeilen (addressLine1/addressLine2) führt die Firma nicht; die gibt es nur an der Betriebsstätte. geoLat/geoLon sind nicht schreibbar, die Koordinaten werden aus der Adresse berechnet.

Neu in V 3.4.0:

• Endet name auf die Anzeigebezeichnung einer Rechtsform aus GET /masterdata/CompanyTypes (z. B. „Musterfirma GmbH"), wird sie serverseitig abgetrennt: Gespeichert wird „Musterfirma", companyTypeId wird aus dem Suffix gesetzt und gewinnt über einen mitgeschickten Wert. Der längste Treffer gilt („GmbH & Co. KG" vor „GmbH"), Groß-/Kleinschreibung spielt keine Rolle, nur ein ganzes Wort am Ende zählt („Musterfirma Agrar" bleibt unangetastet), und ein Name, der nur aus der Rechtsform besteht, bleibt unverändert. Wer den Namen bewusst mit Rechtsform führt, muss damit rechnen, dass er gekürzt wird.
• corporationId ordnet der Firma einen bestehenden Konzern zu. Gültige Werte liefert GET /customers/corporations; eine unbekannte Id liefert 400.
• Enthält location.street Straße und Hausnummer und fehlt streetNumber, zerlegt die API den Wert selbst: Das letzte Wort wird zur Hausnummer, wenn es mit einer Ziffer beginnt.
• Der Aufruf ohne Token liefert 401. Bisher endete er in einem 500.

Request body

Content type: application/json

Responses

200 — OK

400 — Ungültige Anfrage oder Validierungsfehler

Beruf anlegen

POST /customers/{customerId}/professions

Mit diesem Endpunkt kann man einen Beruf anlegen.

Parameters

Request body

Content type: application/json

Responses

200 — OK

400 — Ungültige Anfrage oder Validierungsfehler

404 — Firma nicht gefunden

Firma ändern

PUT /customers/{customerId}

Ändert die Stammdaten einer Firma. Es werden ausschließlich die im Request-Body übermittelten Felder geändert; nicht übermittelte Felder bleiben unverändert (einzige Ausnahme: das Bundesland beim Länderwechsel, siehe unten). Für den Firmenstatus und den Vertragsstatus gibt es eigene Endpunkte (PUT /customers/{customerId}/customerstatus bzw. PUT /customers/{customerId}/contractstatus).

companyTypeId ist beim Ändern optional; wer nur den Namen ändert, muss die Rechtsform nicht mitschicken. Eine Adressänderung berechnet die Koordinaten neu; geoLat/geoLon sind nicht schreibbar.

Neu in V 3.4.0:

• responsibility (userId, officeId) wird ausgewertet und geändert; eine unbekannte Id ergibt 400. Bisher wurde das Objekt stillschweigend verworfen.
• corporationId ordnet der Firma einen bestehenden Konzern zu. Gültige Werte liefert GET /customers/corporations; eine unbekannte Id liefert 400.
• createdAtUtc wird auch beim Ändern übernommen, gedacht für Importe, die das Erstelldatum des Quellsystems nachtragen. Der Änderungszeitpunkt bleibt der Zeitpunkt des Aufrufs.
• Endet ein mitgeschickter name auf die Anzeigebezeichnung einer Rechtsform aus GET /masterdata/CompanyTypes (z. B. „Musterfirma GmbH"), wird sie serverseitig abgetrennt: Gespeichert wird „Musterfirma", companyTypeId wird aus dem Suffix gesetzt, auch ohne mitgeschicktes Feld, und überschreibt einen mitgeschickten Wert. Der längste Treffer gilt, Groß-/Kleinschreibung spielt keine Rolle, nur ein ganzes Wort am Ende zählt, und ein Name, der nur aus der Rechtsform besteht, bleibt unverändert. Wird name nicht mitgeschickt, passiert nichts.
• Länderwechsel: Wird location.countryId auf ein anderes Land geändert und location.federalStateId nicht mitgeschickt, leert die API das gespeicherte Bundesland, so wie talent.Flow beim Länderwechsel. Bisher wurde der Aufruf mit 400 abgelehnt. Ein mitgeschicktes federalStateId muss zum neuen Land gehören, sonst 400 NotMatchCountry auf FederalStateId. Bleibt countryId unverändert, bleibt auch das Bundesland stehen.
• Schlägt die Geokodierung fehl, bleiben vorhandene Koordinaten erhalten, statt auf null zurückzufallen.
• Enthält location.street Straße und Hausnummer und fehlt streetNumber, zerlegt die API den Wert selbst: Das letzte Wort wird zur Hausnummer, wenn es mit einer Ziffer beginnt.

Parameters

Request body

Required.

Zu ändernde Firmendaten. Nur die übermittelten Felder werden geändert.

Content type: application/json

Responses

204 — Firma geändert — die API antwortet ohne Inhalt.

400 — Ungültige Anfrage oder Validierungsfehler

404 — Firma nicht gefunden

Firmen Status ändern

PUT /customers/{customerId}/customerstatus

Erlaubte Werte:

Kunde: Active oder 5000

Interessent: Prospect oder 5001

Ehemaliger Kunde: Former oder 5002

Abgelehnt: Rejected oder 5003

Erlaubte Übergänge, jede andere Kombination wird mit 400 abgelehnt:

Rejected ist nur aus Prospect erreichbar.

Bei einem unzulässigen Übergang enthält validationErrors neben dem allgemeinen Eintrag mit errorType InvalidData einen zweiten Eintrag mit errorType InvalidStatusTransition auf customerStatusId. Dessen value ist ein Objekt mit currentStatus, requestedStatus und allowedTargetStatus (Statusnamen, z. B. "Active"), damit der Client sieht, welche Ziele vom aktuellen Status aus möglich sind.

Das Senden des bereits gesetzten Status ist ein No-op und antwortet mit 204.

Parameters

Request body

Content type: application/json

Responses

204 — Status geändert — die API antwortet ohne Inhalt.

400 — Ungültige Anfrage oder Validierungsfehler. Fachliche Prüfungen antworten als ErrorResponse; scheitert dagegen schon das Binden des Requests (z.B. nicht konvertierbare customerId), liefert das Framework ValidationProblemDetails mit Content-Type application/problem+json.

404 — Firma nicht gefunden

Vertragsabschluss melden

PUT /customers/{customerId}/contractstatus

Meldet einen unterzeichneten Vertrag zu einer Anfrage der Firma. Übergeben werden die Anfrage (requestId), optional der vermittelte Bewerber (candidateId) und der Zeitpunkt der Unterzeichnung (contractSignedAtUtc). Trotz des Pfadnamens contractstatus wird hier kein Statuswert gesetzt; der allgemeine Firmenstatus wird über PUT /customers/{customerId}/customerstatus geändert, der Status einer Anfrage über PUT /customers/{customerId}/requests/{requestId}/status.

Bei Arbeitnehmerüberlassung ist candidateId Pflicht; fehlt sie, kommt 400 mit ErrorType Required auf CandidateId. Einen Endpunkt, um einen Bewerber einer Anfrage zuzuordnen, bietet die Public API nicht; ein Vertragsabschluss lässt sich nur für Bewerber melden, die auf einem anderen Weg zugeordnet wurden.

Neu in V 3.4.0:

• Der Endpunkt bedient Arbeitnehmerüberlassung (EmployeeLeasing) und Personalvermittlung (PersonnelPlacement). Für jede andere Vermittlungsart der Anfrage (None, InternalStaffing, ServiceContract) antwortet er mit 400 und einem Validierungsfehler auf RequestId mit dem ErrorType PlacementTypeNotSupported, der die tatsächliche Vermittlungsart als Wert trägt. Bisher kam in diesen Fällen ein 400 ohne Begründung.
• Ist der Bewerber der Anfrage nicht zugeordnet, antwortet der Endpunkt mit 404 und einem Validierungsfehler auf CandidateId mit dem ErrorType NotAssignedToRequest; existiert der Bewerber nicht, mit 404 und NotExisting. Bisher lief der nicht zugeordnete Bewerber in ein 500 READDATAERROR.

Parameters

Request body

Content type: application/json

Responses

204 — Vertragsabschluss gespeichert, die API antwortet ohne Inhalt.

400 — Ungültige Anfrage oder Validierungsfehler

404 — Firma nicht gefunden