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. The public employee update operation exposes the blocked property. Blocking changes account state; it is not a delete operation and must not be described as data erasure.

​
Block the employee

Use dry run first when the change is part of an automated offboarding process.

​
What the public contract guarantees

  • The employee resource contains a boolean blocked state.
  • The update endpoint can change that state only when no active contract exists.
  • The employee remains addressable by its resource ID while available in scope.
  • The public API does not expose employee deletion.

​
What the public contract does not specify

The OpenAPI contract does not enumerate every downstream portal or business effect of a blocked employee. Do not assume that blocking automatically:
  • deletes employee data
  • cancels, rejects, or archives existing orders
  • deletes incidents or attachments
  • deletes payroll data
  • fulfills a legal erasure request
Handle those processes through the responsible JobHandy and customer business procedures.

​
Reactivation

Only when no active contract exists and the business process permits reactivation, set:
Validate the target state and current tenant scope before applying it.

​
Operational checklist

  • JobHandy employee ID is known
  • Current employee state has been read
  • blocked=true was validated with dry run
  • Real write succeeded and request ID was stored
  • Open orders and incidents were reviewed by the responsible process owner
  • Local access, schedules, secrets, and exports were handled as required
  • Any deletion or data-subject process was routed separately
Last modified on October 20, 2026