Mitarbeiter aktualisieren

curl --request PATCH \
  --url https://api.jobhandy.io/v1/employees/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "firstName": "Alexandra",
  "phoneNumber": "+49 221 5550199",
  "city": "Cologne"
}
'

{
  "id": "68a000000000000000000001",
  "email": "alex.morgan@example.com",
  "privateEmail": "alex.morgan.private@example.net",
  "employeeNumber": "EMP-1042",
  "firstName": "Alex",
  "lastName": "Morgan",
  "phoneNumber": "+49 221 5550100",
  "street": "Example Street 12",
  "postalCode": "50667",
  "city": "Cologne",
  "countryCode": "DE",
  "additionalInfo": "Building B, third floor",
  "blocked": false,
  "tenant": "68a000000000000000000010",
  "divisionId": "68920e08eeaea4f2301eecb3",
  "createdAt": "2026-06-01T08:00:00.000Z",
  "updatedAt": "2026-07-15T11:30:00.000Z"
}

PATCH

https://api.jobhandy.io/v1

employees

{id}

curl --request PATCH \
  --url https://api.jobhandy.io/v1/employees/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "firstName": "Alexandra",
  "phoneNumber": "+49 221 5550199",
  "city": "Cologne"
}
'

{
  "id": "68a000000000000000000001",
  "email": "alex.morgan@example.com",
  "privateEmail": "alex.morgan.private@example.net",
  "employeeNumber": "EMP-1042",
  "firstName": "Alex",
  "lastName": "Morgan",
  "phoneNumber": "+49 221 5550100",
  "street": "Example Street 12",
  "postalCode": "50667",
  "city": "Cologne",
  "countryCode": "DE",
  "additionalInfo": "Building B, third floor",
  "blocked": false,
  "tenant": "68a000000000000000000010",
  "divisionId": "68920e08eeaea4f2301eecb3",
  "createdAt": "2026-06-01T08:00:00.000Z",
  "updatedAt": "2026-07-15T11:30:00.000Z"
}

Auf einen Blick

Eigenschaft	Verhalten
Authentifizierung	Erforderlich in `X-API-Key`
Tenant-Kontext	Optionale Einschränkung; Ressource und Referenzen müssen im Scope bleiben
Dry Run	Unterstützt mit `dryRun=true`
Request-Body	`application/json`; geschlossenes Schema; maximal dokumentierte Body-Größe 5 MiB
Response	JSON
Primärer Erfolg	`200`
Side Effects	Speichert unterstützte Mitarbeiteränderungen; Dry Run unterdrückt die Speicherung
Retry-Empfehlung	Mitarbeiter erneut lesen und gewünschte Felder vergleichen, bevor ein Replay erfolgt

Betriebsverhalten

Aktualisiert Mitarbeiterdaten. divisionId ändert oder entfernt die Division des Mitarbeiters innerhalb desselben Tenants. Dieser Endpoint kann einen bereits zugeordneten Mitarbeiter nicht in einen anderen Tenant verschieben. Mit dryRun=true gibt die API den projizierten Mitarbeiter zurück, ohne ihn zu speichern.

Ausgelassene Eigenschaften bleiben unverändert; nullable Eigenschaften können mit null geleert werden.
divisionId kann die Zuordnung nur innerhalb desselben Tenants ändern oder entfernen.
Mindestens eine Patch-Eigenschaft ist erforderlich.

Häufige Fehler

Fehlercode	Bedeutung
`VALIDATION_ERROR`	Schema- oder fachliche Validierung ist fehlgeschlagen
`INVALID_REQUEST_ID`	`X-Request-ID` ist keine UUID v4 oder v7
`INVALID_API_KEY`	API-Key fehlt, ist ungültig, gelöscht oder inaktiv
`TENANT_NOT_IN_SCOPE`	Ausgewählter Tenant liegt außerhalb des API-Key-Scopes
`NOT_FOUND`	Ressource fehlt oder ist im Scope nicht zugänglich
`NOT_ACCEPTABLE`	Angeforderter Response-Medientyp ist nicht verfügbar
`DUPLICATE_RESOURCE`	Eine Eindeutigkeitsregel wird bereits erfüllt
`PAYLOAD_TOO_LARGE`	Vollständiger Request überschreitet das dokumentierte Limit
`UNSUPPORTED_MEDIA_TYPE`	Request-Medientyp wird nicht akzeptiert
`INVALID_REFERENCE`	Referenzierte Ressource fehlt oder ist nicht verfügbar
`RATE_LIMIT_EXCEEDED`	Rate Limit des API-Keys wurde überschritten
`INTERNAL_SERVER_ERROR`	Unerwarteter Serverfehler

Die Response-Liste der Operation und die Seite Fehlerbehandlung sind für die vollständige Behandlung maßgeblich.

Vor der Implementierung

Erzeugen und protokollieren Sie für den Versuch eine neue X-Request-ID.
Behandeln Sie jeden dokumentierten Response-Status.
Protokollieren Sie weder X-API-Key noch unnötige personenbezogene Daten.
Gleichen Sie den aktuellen Ressourcenstatus ab, bevor Sie einen mehrdeutigen Write wiederholen.

Zugehöriger Integrationsleitfaden

Prüfen Sie den vollständigen Prozess sowie Status-, Retry- und Betriebsmuster für diese Operation.

Autorisierungen

X-API-Key

string

header

erforderlich

JobHandy integration API key. Send the credential in the X-API-Key header. Treat the key as a secret and use it only from trusted server-side environments.

Header

X-Tenant-ID

string

inactive

optional

not sent by default

Narrows the operation to one tenant in the API key's scope. Any referenced or target resource must be accessible through that tenant. In interactive clients, use the {{tenantId}} variable when a tenant must be selected. Keep the header disabled when tenant selection is not required.

Pattern: ^[0-9a-fA-F]{24}$

X-Request-ID

string<uuid>

inactive

optional

not sent by default

Optional request identifier. If supplied, it must be a UUID v4 or v7 and is returned unchanged in every response. If omitted, the API generates one. Invalid values return 400 INVALID_REQUEST_ID. If your client uses a {{requestId}} variable, refresh it with a new UUID version 4 or 7 for every HTTP request attempt. Keep the header disabled to let the API generate the request identifier.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Pfadparameter

string

erforderlich

Employee ID.

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68920e08eeaea4f2301eecb3"

Abfrageparameter

dryRun

boolean

inactive

optional

server default: false

not sent by default

When true, the API validates the request without applying the change. The operation's responses specify the returned representation. When omitted, the server uses false.

Beispiel:

true

Body

application/json

The JSON request body must not exceed 5,242,880 bytes.

Editable employee fields. At least one field is required.

firstName

string

inactive

optional

not sent by default

Replacement first name. Omit the field to leave it unchanged; null is not accepted.

Required string length: 1 - 1000

Pattern: \S

Beispiel:

"Alexandra"

lastName

string

inactive

optional

not sent by default

Replacement last name. Omit the field to leave it unchanged; null is not accepted.

Required string length: 1 - 1000

Pattern: \S

Beispiel:

"Morgan"

privateEmail

string<email> | null

inactive

nullable

optional

not sent by default

Replacement private email address. Use null to clear the stored value.

Beispiel:

"alex.private@example.net"

employeeNumber

string | null

inactive

nullable

optional

not sent by default

Replacement employee number. Use null to clear the stored value.

Beispiel:

"EMP-2042"

phoneNumber

string | null

inactive

nullable

optional

not sent by default

Replacement phone number. Use null to clear the stored value.

Beispiel:

"+49 221 5550199"

street

string | null

inactive

nullable

optional

not sent by default

Replacement street and house number. Use null to clear the stored value.

Maximum string length: 1000

Pattern: \S

Beispiel:

"New Street 7"

postalCode

string | null

inactive

nullable

optional

not sent by default

Replacement postal code. Use null to clear the stored value.

Maximum string length: 1000

Pattern: \S

Beispiel:

"50668"

city

string | null

inactive

nullable

optional

not sent by default

Replacement city. Use null to clear the stored value.

Maximum string length: 1000

Pattern: \S

Beispiel:

"Cologne"

countryCode

enum<string>

inactive

optional

not sent by default

Replacement uppercase two-character country or territory code.

Verfügbare Optionen:

AC,

AD,

AE,

AF,

AG,

AI,

AL,

AM,

AO,

AQ,

AR,

AS,

AT,

AU,

AW,

AX,

AZ,

BA,

BB,

BD,

BE,

BF,

BG,

BH,

BI,

BJ,

BL,

BM,

BN,

BO,

BQ,

BR,

BS,

BT,

BV,

BW,

BY,

BZ,

CA,

CC,

CD,

CF,

CG,

CH,

CI,

CK,

CL,

CM,

CN,

CO,

CR,

CU,

CV,

CW,

CX,

CY,

CZ,

DE,

DJ,

DK,

DM,

DO,

DZ,

EC,

EE,

EG,

EH,

ER,

ES,

ET,

FI,

FJ,

FK,

FM,

FO,

FR,

GA,

GB,

GD,

GE,

GF,

GG,

GH,

GI,

GL,

GM,

GN,

GP,

GQ,

GR,

GS,

GT,

GU,

GW,

GY,

HK,

HM,

HN,

HR,

HT,

HU,

ID,

IE,

IL,

IM,

IN,

IO,

IQ,

IR,

IS,

IT,

JE,

JM,

JO,

JP,

KE,

KG,

KH,

KI,

KM,

KN,

KP,

KR,

KW,

KY,

KZ,

LA,

LB,

LC,

LI,

LK,

LR,

LS,

LT,

LU,

LV,

LY,

MA,

MC,

MD,

ME,

MF,

MG,

MH,

MK,

ML,

MM,

MN,

MO,

MP,

MQ,

MR,

MS,

MT,

MU,

MV,

MW,

MX,

MY,

MZ,

NA,

NC,

NE,

NF,

NG,

NI,

NL,

NO,

NP,

NR,

NU,

NZ,

OM,

PA,

PE,

PF,

PG,

PH,

PK,

PL,

PM,

PN,

PR,

PS,

PT,

PW,

PY,

QA,

RE,

RO,

RS,

RU,

RW,

SA,

SB,

SC,

SD,

SE,

SG,

SH,

SI,

SJ,

SK,

SL,

SM,

SN,

SO,

SR,

SS,

ST,

SV,

SX,

SY,

SZ,

TA,

TC,

TD,

TF,

TG,

TH,

TJ,

TK,

TL,

TM,

TN,

TO,

TR,

TT,

TV,

TW,

TZ,

UA,

UG,

UM,

US,

UY,

UZ,

VA,

VC,

VE,

VG,

VI,

VN,

VU,

WF,

WS,

XK,

YE,

YT,

ZA,

ZM,

ZW

Beispiel:

"DE"

additionalInfo

string | null

inactive

nullable

optional

not sent by default

Replacement additional information. Use null to clear the stored value.

Maximum string length: 1000

Beispiel:

null

blocked

boolean

inactive

optional

not sent by default

Set to true to block the employee account or false to unblock it.

Beispiel:

false

divisionId

string | null

inactive

nullable

optional

not sent by default

New division ID within the current tenant. Use null to remove only the division assignment; this does not move the employee to another tenant.

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68920e08eeaea4f2301eecb4"

Antwort

Returns the updated employee, or the projected employee when dryRun=true.

Employee details.

string

erforderlich

read-only

Unique employee identifier.

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68a000000000000000000001"

string<email>

erforderlich

Work email address used by the employee account. This field is not editable through the update endpoint.

Beispiel:

"alex.morgan@example.com"

blocked

boolean

erforderlich

Whether the employee account is blocked.

Beispiel:

false

tenant

string | null

erforderlich

read-only

nullable

Tenant identifier, or null if the employee has no tenant assignment.

Minimum string length: 1

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68a000000000000000000010"

divisionId

string | null

erforderlich

nullable

Assigned division identifier, or null when no division is assigned.

Minimum string length: 1

Pattern: ^[0-9a-fA-F]{24}$

Beispiel:

"68920e08eeaea4f2301eecb3"

createdAt

string<date-time>

erforderlich

read-only

UTC timestamp at which the employee record was created.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-06-01T08:00:00.000Z"

updatedAt

string<date-time>

erforderlich

read-only

UTC timestamp of the latest employee update.

Minimum string length: 1

Pattern: Z$

Beispiel:

"2026-07-15T11:30:00.000Z"

privateEmail

string | null

nullable

optional

Optional private email address, or null when none is stored.

Beispiel:

"alex.morgan.private@example.net"

employeeNumber

string | null

nullable

optional

Customer-defined personnel or employee number, or null when none is assigned.

Beispiel:

"EMP-1042"

firstName

string | null

nullable

optional

Employee first name, or null when unavailable in an existing record.

Beispiel:

"Alex"

lastName

string | null

nullable

optional

Employee last name, or null when unavailable in an existing record.

Beispiel:

"Morgan"

phoneNumber

string | null

nullable

optional

Employee phone number, or null when none is stored.

Beispiel:

"+49 221 5550100"

street

string | null

nullable

optional

Street and house number, or null when no address is stored.

Beispiel:

"Example Street 12"

postalCode

string | null

nullable

optional

Postal code, or null when no address is stored.

Beispiel:

"50667"

city

string | null

nullable

optional

City, or null when no address is stored.

Beispiel:

"Cologne"

countryCode

string | null

nullable

optional

Uppercase two-character country or territory code, or null when no address is stored.

Beispiel:

"DE"

additionalInfo

string | null

nullable

optional

Additional employee or address information, or null when none is stored.

Beispiel:

"Building B, third floor"

Zuletzt geändert am 27. August 2026

Übersicht

Datenmodelle

Spezifikation

Auf einen Blick

Betriebsverhalten

Häufige Fehler

Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Pfadparameter

Abfrageparameter

Body

Antwort

​Auf einen Blick

​Betriebsverhalten

​Häufige Fehler

​Vor der Implementierung

Zugehöriger Integrationsleitfaden

Autorisierungen

Header

Pfadparameter

Abfrageparameter

Body

Antwort

Auf einen Blick

Betriebsverhalten

Häufige Fehler

Vor der Implementierung