Skip to main content
The JobHandy Public API remains version 1.0.0 on the /v1 base path.

​
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 September 2, 2026