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.

​
Access and API keys

How do I create an API key?

Open JobHandy Administration, go to IT Settings, select API Keys, and click Create API Key. See API Key Management.
At least one of IT, HR, or Company-Admin is required.
Yes. Use separate keys for separate integrations, responsibilities, or scopes.
A key can be scoped to the companies and divisions selected in the administration portal. The API then represents each authorized company as a tenant context.
The documented operational approach does not rely on in-place credential changes. Create a replacement key with the required name and scope, deploy and verify it, then deactivate the old key.
Treat the creation display as the secure capture point. If the credential is unavailable, create and deploy a replacement rather than relying on recovery of a secret value.
Deactivation stops authentication and allows later reactivation. Deletion permanently retires the key from the portal workflow.

​
Environments and testing

Is there a public sandbox or stage base URL?

The public contract documents only https://api.jobhandy.io/v1. Internal development hosts are not part of customer configuration.
No. It validates a supported write against current production scope and state without applying the documented mutation or side effects.
No. It does not lock or reserve state. Revalidate conflicts on the real request.

​
Tenant and scope

What is the difference between Company and Tenant?

Company is the business-facing portal term. Tenant is the technical API boundary and identifier for that organization.
Send it when an operation cannot otherwise resolve one tenant or when you intentionally want to restrict a collection to one authorized tenant.
No. It can only narrow the scope already assigned to the API key.
Use the tenant identifier returned in authorized resource representations or the identifier supplied during integration setup. Do not use a company name or division ID.
Not through PATCH /employees/{id}. The endpoint can change or clear divisionId only within the same tenant.

​
Requests and retries

Is X-Request-ID required?

It is optional but strongly recommended. The API generates one when omitted.
No. It is correlation metadata and does not deduplicate a request.
Re-read or search the affected resource before another write. The server might have committed the mutation before the connection timed out.
No. Request schemas are closed and unknown properties are rejected.
Transient read failures are generally safe to retry with bounded backoff. Respect Retry-After on 429.

​
Collections and filters

What is the maximum page size?

pageSize accepts values from 1 through 1000; the server default is 100.
No. Use exactly one endpoint-supported scalar field, optionally prefixed with - for descending order.
String comparison is case-insensitive. Enum values remain case-sensitive.
Quote values with whitespace and escape an apostrophe with \'. URL-encode the complete filter value.
Snapshot consistency is not guaranteed by the public contract. Use checkpoints and account for concurrent changes.

​
Resources

Can I delete an employee?

No public employee delete operation is defined. Use the documented blocked state for account blocking and handle deletion through the applicable business process.
Work email is not editable through the public employee patch endpoint.
The decision operation is for an order in under_review. A final decision can return ORDER_ALREADY_DECIDED; re-read and reconcile rather than attempting to overwrite it.
No. POST /incidents may return 422 EMPLOYEE_NOT_ACTIVATED and does not create the incident. Complete the employee activation first, then send a new request with a new X-Request-ID.
The endpoint accepts image or PDF attachments for an editable completed incident, subject to file-count and complete-body limits.
The metadata schema explicitly allows null when no file was produced. Do not call the download operation blindly.

​
Operations

What are the numeric rate limits?

The contract defines RateLimit-Policy, RateLimit, and Retry-After headers rather than one global fixed quota. Read the effective values from responses.
The current public v1 contract does not define webhook registration or event-subscription endpoints. Use client-initiated polling.
The OpenAPI specification is the authoritative machine-readable contract. Generate or build a client using the tooling appropriate to your environment and add your own operational controls.
Provide UTC time, method, path, status, error code, request ID, tenant context, and sanitized reproduction steps. Never provide the API key.
Last modified on October 20, 2026