Skip to main content

​
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:
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. Employees are customer-scoped master-data resources. The Public API supports list, create, get, and partial update operations.

​
Capabilities

​
Lifecycle

​
Endpoints

List employees

Page, filter, sort, and restrict employee collections.

Create an employee

Validate placement and create an account.

Get an employee

Retrieve one employee by opaque ID.

Update an employee

Patch supported fields, division assignment, and blocking state.

​
Key rules

  • Store the JobHandy employee ID after match or create.
  • Use a stable customer identifier such as employeeNumber where uniqueness is guaranteed.
  • Do not use email as the only long-term key unless the customer guarantees immutability.
  • Omit patch fields that should remain unchanged.
  • Use null only for nullable fields that should be cleared.
  • Do not use a dry-run preview ID in later requests.

Employee synchronization guide

Implement identity matching, checkpoints, dry runs, partial updates, and timeout reconciliation.
Last modified on October 20, 2026