Synchronize employees

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	Set explicitly; do not treat as 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
`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

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

​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

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