Create an employee
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.
At a glance
Operational behavior
Creates an employee account and sends a password setup email. UseX-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
Before implementation
- Generate and log a new
X-Request-IDfor the attempt. - Handle every documented response status.
- Do not log
X-API-Keyor unnecessary personal data. - Reconcile current resource state before replaying an ambiguous write.
Related integration guidance
Authorizations
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
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.
^[0-9a-fA-F]{24}$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.
^[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
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.
true
Body
The JSON request body must not exceed 5,242,880 bytes.
Fields accepted when creating an employee account.
Work email address used to activate and access the employee account.
"alex.morgan@example.com"
Employee first name.
1 - 1000\S"Alex"
Employee last name.
1 - 1000\S"Morgan"
Optional private email address.
"alex.morgan.private@example.net"
Optional customer-defined personnel or employee number.
"EMP-1042"
Optional employee phone number.
"+49 221 5550100"
Optional street and house number.
1000\S"Example Street 12"
Optional postal code.
1000\S"50667"
Optional city.
1000\S"Cologne"
Uppercase two-letter ISO country or territory code.
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 "DE"
Optional additional employee or address information.
1000"Building B, third floor"
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.
^[0-9a-fA-F]{24}$"68920e08eeaea4f2301eecb3"
Response
Dry-run validation succeeded. Returns the employee that would be created; no account is stored and no email is sent.
Employee details.
Unique employee identifier.
^[0-9a-fA-F]{24}$"68a000000000000000000001"
Work email address used by the employee account. This field is not editable through the update endpoint.
"alex.morgan@example.com"
Whether the employee account is blocked.
false
Tenant identifier, or null if the employee has no tenant assignment.
1^[0-9a-fA-F]{24}$"68a000000000000000000010"
Assigned division identifier, or null when no division is assigned.
1^[0-9a-fA-F]{24}$"68920e08eeaea4f2301eecb3"
UTC timestamp at which the employee record was created.
1Z$"2026-06-01T08:00:00.000Z"
UTC timestamp of the latest employee update.
1Z$"2026-07-15T11:30:00.000Z"
Optional private email address, or null when none is stored.
"alex.morgan.private@example.net"
Customer-defined personnel or employee number, or null when none is assigned.
"EMP-1042"
Employee first name, or null when unavailable in an existing record.
"Alex"
Employee last name, or null when unavailable in an existing record.
"Morgan"
Employee phone number, or null when none is stored.
"+49 221 5550100"
Street and house number, or null when no address is stored.
"Example Street 12"
Postal code, or null when no address is stored.
"50667"
City, or null when no address is stored.
"Cologne"
Uppercase two-character country or territory code, or null when no address is stored.
"DE"
Additional employee or address information, or null when none is stored.
"Building B, third floor"
