Skip to main content
Production REST + JSON OpenAPI 3.1 The JobHandy Public API is a server-to-server interface for synchronizing employee master data, processing HR order decisions, reporting incidents, maintaining organizational divisions, and retrieving payroll export documents.

Production base URL

https://api.jobhandy.io/v1

Authentication

X-API-Key on every protected request

Request correlation

UUID v4 or v7 in X-Request-ID

Create an API key

Create a scoped credential in the JobHandy administration portal.

Start the quickstart

Verify connectivity, authenticate, read employees, and validate a write.

Browse API reference

Review every operation, parameter, response, schema, and error case.

Download OpenAPI

Use the authoritative OpenAPI 3.1 contract in JSON or YAML format.

​
Integration context

The customer integration owns scheduling, mapping, retry control, checkpoints, secret storage, and downstream processing. JobHandy validates the request, enforces the API-key scope, applies the documented state rules, and returns a request ID for correlation.

​
What you can build

Employee synchronization

Create employees, update supported fields, assign divisions, and block or unblock accounts.

HR order review

Retrieve orders under review and record an approval or rejection decision.

Incident reporting

Create and update employee incidents and upload permitted supporting files.

Organization structure

Create and maintain tenant-owned division hierarchies and cost centers.

Payroll retrieval

Discover payroll export metadata and download available files.

Operational monitoring

Check basic public API availability without an API key.

​
Core rules

Production endpoint only

Public integrations use https://api.jobhandy.io/v1. Internal development or stage hosts are not part of the public contract.
An API key can access only the tenants and divisions selected in its scope. X-Tenant-ID can narrow that scope but never expand it.
Supported writes accept dryRun=true. The request is validated against current production scope and state, but the documented mutation and side effects are not applied.
Request schemas are closed. Send only documented properties and media types.
X-Request-ID correlates requests and responses. It does not deduplicate writes or make a retry safe.

​
Resource model

See Architecture and resource model for ownership, relationships, and terminology.
1

Create a dedicated API key

Select only the companies and divisions required by the integration.
2

Complete the quickstart

Verify health, authentication, tenant selection, request IDs, and dry-run validation.
3

Implement one integration guide

Follow the matching employee, order, incident, division, or payroll workflow.
4

Complete the go-live checklist

Validate secret storage, retries, reconciliation, monitoring, and support readiness.

Review the go-live checklist

Confirm that the integration is safe to operate before enabling production schedules.
Last modified on August 28, 2026