Skip to main content
POST
cURL

Auf einen Blick

Betriebsverhalten

Erstellt ein Mitarbeiterkonto und sendet eine E-Mail zur Passwortvergabe. Verwenden Sie X-Tenant-ID oder divisionId, um den Tenant auszuwählen. Bei einem divisionsbeschränkten API-Key darf divisionId nur fehlen, wenn der ausgewählte Tenant genau eine zulässige Division besitzt; andernfalls muss eine erlaubte Division angegeben werden. Fehlen beide Selektoren, muss der API-Key genau einen Tenant ergeben. Mit dryRun=true gibt die API den projizierten Mitarbeiter zurück, ohne das Konto zu erstellen oder eine E-Mail zu senden.
  • Geben Sie bei einem divisionsbeschränkten Key divisionId an, sofern nicht genau eine zulässige Division ermittelt werden kann.
  • Speichern Sie keine Vorschau-ID aus einem Dry Run.
  • Die geschäftliche E-Mail-Adresse kann später nicht über den öffentlichen Employee-Patch-Endpoint geändert werden.

Häufige Fehler

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

Tenant in which to create the resource. If omitted, the API infers the tenant as described for this operation. 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}$

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.

Fields accepted when creating an employee account.

email
string<email>
erforderlich

Work email address used to activate and access the employee account.

Beispiel:

"alex.morgan@example.com"

firstName
string
erforderlich

Employee first name.

Required string length: 1 - 1000
Pattern: \S
Beispiel:

"Alex"

lastName
string
erforderlich

Employee last name.

Required string length: 1 - 1000
Pattern: \S
Beispiel:

"Morgan"

privateEmail
string<email>
inactive
optional
not sent by default

Optional private email address.

Beispiel:

"alex.morgan.private@example.net"

employeeNumber
string
inactive
optional
not sent by default

Optional customer-defined personnel or employee number.

Beispiel:

"EMP-1042"

phoneNumber
string
inactive
optional
not sent by default

Optional employee phone number.

Beispiel:

"+49 221 5550100"

street
string
inactive
optional
not sent by default

Optional street and house number.

Maximum string length: 1000
Pattern: \S
Beispiel:

"Example Street 12"

postalCode
string
inactive
optional
not sent by default

Optional postal code.

Maximum string length: 1000
Pattern: \S
Beispiel:

"50667"

city
string
inactive
optional
not sent by default

Optional city.

Maximum string length: 1000
Pattern: \S
Beispiel:

"Cologne"

countryCode
enum<string>
inactive
optional
not sent by default

Uppercase two-letter ISO 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
inactive
optional
not sent by default

Optional additional employee or address information.

Maximum string length: 1000
Beispiel:

"Building B, third floor"

divisionId
string | null
inactive
nullable
optional
not sent by default

Initial division ID. If omitted or null, the API infers placement from X-Tenant-ID or the API-key scope as documented by the operation.

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

"68920e08eeaea4f2301eecb3"

Antwort

Dry-run validation succeeded. Returns the employee that would be created; no account is stored and no email is sent.

Employee details.

id
string
erforderlich
read-only

Unique employee identifier.

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

"68a000000000000000000001"

email
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