Skip to main content
The current JobHandy Public API contract version is 2.0.0. The documented production base URL remains https://api.jobhandy.io/v1.

​
2.0.0 - Breaking change

This version is not fully backward compatible with integrations built against 1.0.0. Request fields remain unchanged; processing and validation behavior change.

​
Incidents

  • POST /incidents requires a contract in status active; approved is insufficient.
  • Without an active contract: HTTP 422 with EMPLOYEE_HAS_NO_ACTIVE_CONTRACT, including with dryRun=true.
  • Existing incidents remain editable.

​
Employees

  • With an active contract, both blocked: true and blocked: false are prohibited in PATCH /employees/{id}.
  • The API rejects the entire patch with HTTP 422 and EMPLOYEE_HAS_ACTIVE_CONTRACT, including with dryRun=true. Other fields are not partially applied.

​
Migration

Omit blocked entirely for profile-only changes, including automatically inserted defaults. Update contract checks, error handling, mappings, and tests for both writes and dry runs. Do not retry unchanged requests rejected by business validation. Complete migration guidance.

​
2026-09-02 - 1.0.0

​
Incidents

  • POST /incidents now returns 422 EMPLOYEE_NOT_ACTIVATED when the referenced employee exists in the authorized scope but has not completed activation.
  • The error message is The referenced employee is not activated.
  • No incident is created when this validation fails.

​
Client impact

Do not retry the same create request until employee activation has completed. After activation, submit a new request with a new X-Request-ID.

​
2026-08-28 - 1.0.0

​
Orders

  • Removed tenant and divisionId from the Order response schema.
  • Replaced hrReviewDecision and OrderHrReviewDecision with hrHistory and OrderHrHistory.
  • hrHistory.decisionBy now contains a nullable 24-character user ID. It is null for automated and API-key decisions.
  • Replaced the OrderProduct model returned in products[] by GET /orders, GET /orders/{id}, and POST /orders/{id}/decision.
  • Added model, vatRate, manufacturerName, articleGroupName, grossAmount, netAmount, service, grossService, and netService to OrderProduct.
  • Removed description, rateInCents, and serviceRateInCents from OrderProduct.
  • model, manufacturerName, articleGroupName, service, grossService, and netService are nullable.
  • vatRate and grossAmount are decimal strings with two decimal places; netAmount uses four decimal places. grossService and netService are nullable decimal strings with two decimal places.

​
Order queries

  • Removed tenant and divisionId from the supported filter and sort fields of GET /orders.
  • Use X-Tenant-ID to restrict an order query to one authorized tenant where required.

​
Divisions

  • Changed Division.order, DivisionCreate.order, and DivisionPatch.order from OpenAPI type integer to number.
  • Removed the previous integer-only multipleOf: 1 constraint.

​
Client impact

The API version remains 1.0.0 and the production base URL remains https://api.jobhandy.io/v1. Clients that deserialize order responses must update their models, DTOs, mappings, decimal handling, mocks, and contract tests. Do not infer tenant or division from fields that are no longer present in the Order response.

​
Initial public scope

​
Available resources

  • Employees: list, create, get, update
  • Orders: list, get, HR decision, attachment download
  • Incidents: list, create, get, update, attachment upload
  • Divisions: list, create, get, update
  • Payroll export documents: list, get, download
  • Health: public availability check

​
Cross-cutting behavior

  • X-API-Key authentication
  • optional X-Tenant-ID tenant selection where documented
  • UUID v4/v7 X-Request-ID correlation
  • page-based collection pagination
  • one-field sorting
  • filter expression language
  • dry-run validation on supported writes
  • common structured error envelope
  • rate-limit response headers
The OpenAPI document does not encode a publication date for this baseline. Future entries should include an explicit release date and migration impact.

​
Future entry format

​
Client responsibility

Before adopting a new OpenAPI file:
  1. Compare it with the version currently used by the client.
  2. Identify request, response, schema, enum, endpoint, and error changes.
  3. Regenerate or update client types.
  4. Run contract and acceptance tests.
  5. Record the adopted version and checksum.

Versioning policy

Review which changes are additive and which require migration.
Last modified on October 20, 2026