Skip to main content
POST
cURL

At a glance

Operational behavior

Creates an employee account and sends a password setup email. Use X-Tenant-ID or divisionId to select the tenant. For a division-restricted API key, omit divisionId only when the selected tenant has exactly one allowed division; otherwise supply an allowed division. If both selectors are omitted, the API key must resolve to one tenant. With dryRun=true, the API returns the projected employee without creating the account or sending email.
  • For a division-restricted key, supply divisionId unless exactly one allowed division can be inferred.
  • Do not store a preview ID returned by dry run.
  • The work email cannot later be changed through the public employee patch endpoint.

Common errors

The operation response list and Error handling page are authoritative for complete handling.

Before implementation

  • Generate and log a new X-Request-ID for the attempt.
  • Handle every documented response status.
  • Do not log X-API-Key or unnecessary personal data.
  • Reconcile current resource state before replaying an ambiguous write.

Related integration guidance

Review the complete process, state, retry, and operational pattern for this operation.

Authorizations

X-API-Key
string
header
required

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.

Headers

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}$

Query Parameters

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.

Example:

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>
required

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

Example:

"alex.morgan@example.com"

firstName
string
required

Employee first name.

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

"Alex"

lastName
string
required

Employee last name.

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

"Morgan"

privateEmail
string<email>
inactive
optional
not sent by default

Optional private email address.

Example:

"alex.morgan.private@example.net"

employeeNumber
string
inactive
optional
not sent by default

Optional customer-defined personnel or employee number.

Example:

"EMP-1042"

phoneNumber
string
inactive
optional
not sent by default

Optional employee phone number.

Example:

"+49 221 5550100"

street
string
inactive
optional
not sent by default

Optional street and house number.

Maximum string length: 1000
Pattern: \S
Example:

"Example Street 12"

postalCode
string
inactive
optional
not sent by default

Optional postal code.

Maximum string length: 1000
Pattern: \S
Example:

"50667"

city
string
inactive
optional
not sent by default

Optional city.

Maximum string length: 1000
Pattern: \S
Example:

"Cologne"

countryCode
enum<string>
inactive
optional
not sent by default

Uppercase two-letter ISO country or territory code.

Available options:
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
Example:

"DE"

additionalInfo
string
inactive
optional
not sent by default

Optional additional employee or address information.

Maximum string length: 1000
Example:

"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}$
Example:

"68920e08eeaea4f2301eecb3"

Response

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

Employee details.

id
string
required
read-only

Unique employee identifier.

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

"68a000000000000000000001"

email
string<email>
required

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

Example:

"alex.morgan@example.com"

blocked
boolean
required

Whether the employee account is blocked.

Example:

false

tenant
string | null
required
read-only
nullable

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

Minimum string length: 1
Pattern: ^[0-9a-fA-F]{24}$
Example:

"68a000000000000000000010"

divisionId
string | null
required
nullable

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

Minimum string length: 1
Pattern: ^[0-9a-fA-F]{24}$
Example:

"68920e08eeaea4f2301eecb3"

createdAt
string<date-time>
required
read-only

UTC timestamp at which the employee record was created.

Minimum string length: 1
Pattern: Z$
Example:

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

updatedAt
string<date-time>
required
read-only

UTC timestamp of the latest employee update.

Minimum string length: 1
Pattern: Z$
Example:

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

privateEmail
string | null
nullable
optional

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

Example:

"alex.morgan.private@example.net"

employeeNumber
string | null
nullable
optional

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

Example:

"EMP-1042"

firstName
string | null
nullable
optional

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

Example:

"Alex"

lastName
string | null
nullable
optional

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

Example:

"Morgan"

phoneNumber
string | null
nullable
optional

Employee phone number, or null when none is stored.

Example:

"+49 221 5550100"

street
string | null
nullable
optional

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

Example:

"Example Street 12"

postalCode
string | null
nullable
optional

Postal code, or null when no address is stored.

Example:

"50667"

city
string | null
nullable
optional

City, or null when no address is stored.

Example:

"Cologne"

countryCode
string | null
nullable
optional

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

Example:

"DE"

additionalInfo
string | null
nullable
optional

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

Example:

"Building B, third floor"

Last modified on August 27, 2026