Synchronize employees

API 2.0.0: blocking changes and active contracts

For PATCH /employees/{id}, an active contract prohibits both blocked: true and blocked: false. If blocked is included, the API rejects the entire patch with HTTP 422 and EMPLOYEE_HAS_ACTIVE_CONTRACT, including when dryRun=true. Other fields in that rejected request are not applied. Sending the employee’s existing blocked value does not avoid this rule. For profile-only updates, omit blocked entirely. Configure serializers and synchronization mappings so they do not add blocked: false as a default. For example:

{
  "phoneNumber": "+49 221 5550199"
}

Do not retry an unchanged rejected patch. Resolve the blocking request through the responsible business process, or, for an independently intended profile update, send a new patch containing only the intended supported profile fields. A successful dry run does not reserve contract state; handle the same validation on the real write. A reliable synchronization separates identity matching, tenant placement, validation, mutation, and checkpointing. Never create a new JobHandy employee on every import run.

Source-of-truth model

Before implementation, assign ownership for every mapped field.

Field group	Recommended owner	Integration behavior
Work email	HR/customer process at creation; not patchable through this endpoint	Treat change as a separate business process
Employee number	Customer HR system when stable	Use as a matching key where uniqueness is guaranteed
Contact and address data	Agreed source system	Patch only changed supported fields
`blocked`	Agreed offboarding/account process	Omit for profile-only updates; set explicitly only without an active contract; not deletion
Tenant	Placement process	Resolve on create; public patch does not transfer assigned employees
Division	HR organization source	Patch within the same tenant or clear with `null`
JobHandy `id`	JobHandy	Persist after match or create and use for later requests

Matching order

Stored JobHandy employee ID
Stable employeeNumber when the source guarantees uniqueness
Another explicitly agreed unique mapping
Email only when the customer guarantees it is immutable and unique

If a query returns zero or more than one plausible match, stop automated creation and route the record for reconciliation.

Synchronization swimlane

Resolve placement

Send X-Tenant-ID when the key includes multiple possible tenants.
Send divisionId when the selected tenant does not resolve one permitted division.
Use only a division inside the target tenant and API-key scope.
divisionId: null removes the division assignment but does not transfer the employee.

Find an employee

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant-ID: {{tenantId}}' \
  --data-urlencode 'filter=employeeNumber=EMP-1042'

Persist the returned JobHandy id after a successful match.

Create safely

Confirm no existing match

Search by the stored JobHandy ID or stable employee number.

Validate placement and payload

Call POST /employees?dryRun=true with the final headers and body.

Apply the create

Send the same request without dryRun=true.

Persist the real ID

Store only the ID returned by the non-dry-run 201 response.

Record the side effect

A successful create sends a password setup email. Do not create duplicate accounts to repeat that email.

Patch only changed fields

{
  "phoneNumber": "+49 221 1234567",
  "divisionId": "68920e08eeaea4f2301eecb3"
}

Nullable patch properties can be cleared with null. Omit properties that should remain unchanged.

{
  "phoneNumber": null,
  "divisionId": null
}

Checkpoint model

Persist at least:

sourceEmployeeId
jobHandyEmployeeId
sourceVersion or watermark
lastSuccessfulAtUtc
lastRequestId
lastResult

Timeout reconciliation

Common failures

Error	Meaning	Action
`DUPLICATE_RESOURCE`	A uniqueness rule is already satisfied by another record	Locate and reconcile the existing employee
`EMPLOYEE_PLACEMENT_AMBIGUOUS`	Division-restricted scope does not resolve one target	Send an allowed `divisionId`
`TENANT_CONTEXT_AMBIGUOUS`	More than one tenant is possible	Send `X-Tenant-ID`
`INVALID_REFERENCE`	Referenced tenant or division is unavailable	Refresh scope and references
`EMPLOYEE_HAS_ACTIVE_CONTRACT`	422: active contract and `blocked` included; entire patch rejected	Omit `blocked` for profile-only updates
`409` or `422` after dry run	State changed or final validation differs	Re-read and revalidate; do not blind retry

Get Started

Architecture & Concepts

Integration Guides

Operations

API 2.0.0: blocking changes and active contracts

Source-of-truth model

Matching order

Synchronization swimlane

Resolve placement

Find an employee

Create safely

Patch only changed fields

Checkpoint model

Timeout reconciliation

Common failures

​API 2.0.0: blocking changes and active contracts

​Source-of-truth model

​Matching order

​Synchronization swimlane

​Resolve placement

​Find an employee

​Create safely

​Patch only changed fields

​Checkpoint model

​Timeout reconciliation

​Common failures

API 2.0.0: blocking changes and active contracts

Source-of-truth model

Matching order

Synchronization swimlane

Resolve placement

Find an employee

Create safely

Patch only changed fields

Checkpoint model

Timeout reconciliation

Common failures