Skip to main content

​
API 2.0.0: active contract required

POST /incidents requires a contract with status active. Status approved is insufficient. Without an active contract, the request fails with HTTP 422 and EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including when dryRun=true; no incident is created. Resolve the contract state through the responsible business process before submitting a new request with a new X-Request-ID. Existing incidents remain editable under their existing lifecycle and field restrictions. This new prerequisite applies to creation. The employee activation prerequisite remains documented separately; no precedence between validation errors is specified.

​
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 contract documents one production base URL:
Internal development or stage hosts are not part of the customer-facing contract and must not be embedded in public client configuration.

​
Dry run versus separate environment

dryRun=true is a request mode on supported write operations. It is not a sandbox and does not use a separate database.

​
Safe test strategy

1

Use a dedicated key

Create a key with the minimum company and division scope required for development or acceptance testing.
2

Use agreed test records

Coordinate test employees, orders, incidents, divisions, and payroll periods with the responsible customer administrators.
3

Validate writes first

Use dryRun=true on supported operations and inspect the projected resource and error behavior.
4

Apply a controlled write

Perform one real request in the agreed scope and verify all persistence and side effects.
5

Test recovery

Exercise timeouts, 409, 422, 429, and credential deactivation before enabling automation.

​
What health does and does not prove

GET /health proves that the public API is reachable and can return its health response. It does not prove:
  • API-key validity
  • tenant or division scope
  • access to a specific resource
  • availability of a downstream document file
  • correctness of a write payload
Use at least one protected read and one supported dry run for an end-to-end integration check.
Do not use an undocumented internal host as a fallback. A client should fail safely if the production base URL is unavailable.
Last modified on October 20, 2026