# JobHandy Developers

> Official JobHandy API documentation for secure HR, workforce, order, incident, division, and payroll integrations.

## Documentation

### Get Started

- [JobHandy Public API](https://developers.jobhandy.io/get-started/introduction.md): Build secure, production-grade HR and payroll integrations with the JobHandy Public API.
- [Create and manage API keys](https://developers.jobhandy.io/get-started/api-key-management.md): Create, scope, deactivate, reactivate, rotate, and delete JobHandy API keys in the administration portal.
- [Authentication and access scope](https://developers.jobhandy.io/get-started/authentication.md): Authenticate requests with X-API-Key, select tenant context, and handle credential failures.
- [Quickstart](https://developers.jobhandy.io/get-started/quickstart.md): Create a credential, verify connectivity, authenticate, query employees, and validate a write without persistence.
- [Go-live checklist](https://developers.jobhandy.io/get-started/go-live-checklist.md): Verify security, correctness, resilience, observability, and operational readiness before production activation.

### Architecture & Concepts

- [Architecture and resource model](https://developers.jobhandy.io/concepts/architecture-resource-model.md): Understand system boundaries, resource ownership, relationships, and the responsibilities of each integration component.
- [Terminology](https://developers.jobhandy.io/concepts/terminology.md): Use consistent definitions for companies, tenants, divisions, users, credentials, scope, and resources.
- [Environments and testing](https://developers.jobhandy.io/concepts/environments-testing.md): Understand the public production endpoint, dry-run validation, test-data responsibilities, and safe rollout practices.
- [Tenant scope and resource placement](https://developers.jobhandy.io/concepts/tenant-scope.md): Resolve tenant context, division placement, and API-key authorization without ambiguity.
- [Request and response conventions](https://developers.jobhandy.io/concepts/request-response.md): Apply consistent URLs, headers, media types, schema behavior, response envelopes, and binary download handling.
- [Data types and formats](https://developers.jobhandy.io/concepts/data-types-formats.md): Use the exact identifier, timestamp, date, month, country, enum, money, nullability, and file conventions.
- [Pagination, filtering, and sorting](https://developers.jobhandy.io/concepts/pagination-filtering.md): Build precise collection queries with page traversal, one-field sorting, UTC windows, and the filter expression language.
- [Dry-run validation](https://developers.jobhandy.io/concepts/dry-runs.md): Validate supported writes against current scope and state without persistence or documented side effects.
- [Request IDs and correlation](https://developers.jobhandy.io/concepts/request-ids.md): Use X-Request-ID to correlate clients, API responses, retries, logs, and support investigations.
- [Retries, idempotency, and ambiguous outcomes](https://developers.jobhandy.io/concepts/retries-idempotency.md): Retry only when replay is safe and reconcile write timeouts by reading the current resource state.
- [Error handling](https://developers.jobhandy.io/concepts/error-handling.md): Interpret the common error envelope, classify failures, decide retry behavior, and collect actionable diagnostics.
- [Rate limits and backoff](https://developers.jobhandy.io/concepts/rate-limits.md): Read quota headers, honor Retry-After, and control concurrency without relying on an undocumented fixed limit.
- [Security and data protection](https://developers.jobhandy.io/concepts/security-data-protection.md): Protect credentials, personal data, incident evidence, payroll files, logs, and operational access throughout the integration.
- [Capabilities and limitations](https://developers.jobhandy.io/concepts/capabilities-limitations.md): Know which functions are available in public v1 and which workflows remain outside the current API contract.
- [Versioning and compatibility](https://developers.jobhandy.io/concepts/versioning.md): Understand URL versioning, additive changes, breaking changes, enum evolution, and contract-update responsibilities.

### Integration Guides

- [Synchronize employees](https://developers.jobhandy.io/guides/sync-employees.md): Design a resumable employee synchronization with stable identity, explicit placement, dry-run validation, partial updates, and reconciliation.
- [Employee offboarding](https://developers.jobhandy.io/guides/employee-offboarding.md): Block access, preserve referential integrity, document limitations, and separate account state from deletion or erasure workflows.
- [Process orders and HR decisions](https://developers.jobhandy.io/guides/process-orders.md): Retrieve orders under HR review, validate one final decision, reconcile timeouts, and download order documents.
- [Manage employee incidents](https://developers.jobhandy.io/guides/manage-incidents.md): Create incidents, synchronize server-managed lifecycle state, update supported dates, and upload permitted evidence files.
- [Manage division hierarchies](https://developers.jobhandy.io/guides/manage-divisions.md): Create and update tenant-owned organizational divisions without cross-tenant moves, hierarchy cycles, or sibling-name conflicts.
- [Retrieve payroll export documents](https://developers.jobhandy.io/guides/payroll-exports.md): Discover payroll export metadata, select by tenant, format, and month range, and download an available file safely.
- [Rotate API keys](https://developers.jobhandy.io/guides/rotate-api-keys.md): Replace a JobHandy API key without downtime and retire the old credential after verification.

### Operations

- [Tooling and OpenAPI](https://developers.jobhandy.io/operations/tooling-openapi.md): Import the OpenAPI contract into API clients, generate typed clients, validate requests, and control contract updates.
- [Troubleshooting](https://developers.jobhandy.io/operations/troubleshooting.md): Diagnose connectivity, authentication, scope, validation, state conflicts, throttling, timeouts, and download failures.
- [Frequently asked questions](https://developers.jobhandy.io/operations/faq.md): Answers to common questions about credentials, environments, scope, requests, resources, retries, and operations.
- [Support and escalation](https://developers.jobhandy.io/operations/support.md): Prepare a complete, secure diagnostic record before escalating an integration issue through the established JobHandy support channel.
- [API changelog](https://developers.jobhandy.io/operations/changelog.md): Track public API and schema changes, client impact, deprecations, and migration requirements.

## API Reference

### Overview

- [JobHandy Public API reference](https://developers.jobhandy.io/api-reference/overview.md): Authoritative reference for JobHandy operations, request behavior, resources, errors, and the OpenAPI 3.1 contract.

### Employees

- [Employees](https://developers.jobhandy.io/api-reference/employees.md): Employee master data, tenant placement, division assignment, account blocking, and synchronization operations.
- [List employees](https://developers.jobhandy.io/api-reference/employees/list-employees.md): Lists employees in the API key's scope. Filter and sort fields: `id`, `email`, `privateEmail`, `employeeNumber`, `firstName`, `lastName`, `phoneNumber`, `street`, `postalCode`, `city`, `countryCode`, `additionalInfo`, `blocked`, `tenant`, `divisionId`, `createdAt`, `updatedAt`.
- [Create an employee](https://developers.jobhandy.io/api-reference/employees/create-employee.md): Creates an employee account and sends a password setup email. Use `X-Tenant-ID` or `divisionId` to select the tenant. For a division-restricted API key, omit `divisionId` only when the selected tenant has exactly one allowed division; otherwise supply an allowed division. If both selectors are omitt…
- [Get an employee](https://developers.jobhandy.io/api-reference/employees/get-employee.md): Returns the employee if it is in the API key's scope.
- [Update an employee](https://developers.jobhandy.io/api-reference/employees/update-employee.md): Updates employee data. `divisionId` changes or removes the employee's division within the same tenant. This endpoint cannot move an assigned employee to another tenant. With `dryRun=true`, the API returns the projected employee without saving it.

### Orders

- [Orders](https://developers.jobhandy.io/api-reference/orders.md): Order retrieval, HR decisions, contract data, products, and downloadable order documents.
- [List orders](https://developers.jobhandy.io/api-reference/orders/list-orders.md): Lists orders in the API key's scope. Filter and sort fields: `id`, `status`, `employee`, `orderNumber`, `createdAt`, `updatedAt`, `contractDurationInMonths`, `contractStartDate`, `contractEndDate`.
- [Get an order](https://developers.jobhandy.io/api-reference/orders/get-order.md): Returns the order if it is in the API key's scope.
- [Approve or reject an order](https://developers.jobhandy.io/api-reference/orders/decide-order.md): Approves or rejects an order that is under HR review. Approval applies the documented contract date defaults and sends the corresponding notifications. With `dryRun=true`, the API returns the projected order without applying the decision or sending notifications.
- [Download an order attachment](https://developers.jobhandy.io/api-reference/orders/download-attachment.md): Downloads the contract document referenced by an order attachment.

### Incidents

- [Incidents](https://developers.jobhandy.io/api-reference/incidents.md): Employee incident reporting, server-managed lifecycle state, supported updates, and evidence attachments.
- [List incidents](https://developers.jobhandy.io/api-reference/incidents/list-incidents.md): Lists employee incidents in the API key's scope. Filter and sort fields: `id`, `employeeIncidentNumber`, `type`, `status`, `employee`, `reportedBy`, `reportedAt`, `dateFrom`, `dateUntil`, `createdAt`, `updatedAt`.
- [Create an incident](https://developers.jobhandy.io/api-reference/incidents/create-incident.md): Reports an employee incident for an authorized, activated employee. The API assigns the reporter and lifecycle status. With `dryRun=true`, the API returns the projected incident without saving it.
- [Get an incident](https://developers.jobhandy.io/api-reference/incidents/get-incident.md): Returns the incident if its employee is in the API key's scope.
- [Update an incident](https://developers.jobhandy.io/api-reference/incidents/update-incident.md): Updates editable incident fields. Setting `dateUntil` closes or schedules completion of an open temporary incident. Incidents cannot be reopened. With `dryRun=true`, the API returns the projected incident without saving it.
- [Upload incident attachments](https://developers.jobhandy.io/api-reference/incidents/upload-attachments.md): Adds image or PDF attachments to an editable completed employee incident. With `dryRun=true`, the API validates the files without storing them.

### Divisions

- [Divisions](https://developers.jobhandy.io/api-reference/divisions.md): Tenant-owned organizational hierarchy, parent-child relationships, sibling order, and cost-center assignment.
- [List divisions](https://developers.jobhandy.io/api-reference/divisions/list-divisions.md): Lists divisions in the API key's scope. Filter and sort fields: `id`, `tenant`, `name`, `parentId`, `order`, `costCenter`, `createdAt`, `updatedAt`.
- [Create a division](https://developers.jobhandy.io/api-reference/divisions/create-division.md): Creates a division. `X-Tenant-ID` selects the tenant. If omitted, the API infers the tenant from `parentId` or the API key's scope; the request fails if this is ambiguous. With `dryRun=true`, the API returns the projected division without saving it.
- [Get a division](https://developers.jobhandy.io/api-reference/divisions/get-division.md): Returns the division if it is in the API key's scope.
- [Update a division](https://developers.jobhandy.io/api-reference/divisions/update-division.md): Updates a division. If supplied, `X-Tenant-ID` must match the division's tenant. With `dryRun=true`, the API returns the projected division without saving it.

### Payroll export documents

- [Payroll export documents](https://developers.jobhandy.io/api-reference/payroll-export-documents.md): Read-only payroll export metadata, supported formats, covered periods, and available file downloads.
- [List payroll export documents](https://developers.jobhandy.io/api-reference/payroll-export-documents/list.md): Lists payroll export documents in the API key's scope. Filter and sort fields: `tenant`, `type`, `startMonth`, `endMonth`.
- [Get a payroll export document](https://developers.jobhandy.io/api-reference/payroll-export-documents/get.md): Returns payroll export document metadata if it is in the API key's scope.
- [Download a payroll export document](https://developers.jobhandy.io/api-reference/payroll-export-documents/download.md): Downloads the file associated with a payroll export document.

### Health

- [Health](https://developers.jobhandy.io/api-reference/health.md): Public basic availability endpoint for connectivity checks without API-key authentication.
- [Get public API health](https://developers.jobhandy.io/api-reference/health/get-health.md): Returns the current availability of the public API.

### Data Models

- [Employee](https://developers.jobhandy.io/api-reference/models/employee.md): Employee resource including contact data, account state, tenant, and division placement.
- [Order](https://developers.jobhandy.io/api-reference/models/order.md): Employee order including products, HR review data, contract dates, delivery address, and attachments.
- [Incident](https://developers.jobhandy.io/api-reference/models/incident.md): Employee incident lifecycle, reporter metadata, dates, and current state.
- [Division](https://developers.jobhandy.io/api-reference/models/division.md): Tenant-owned organizational division with hierarchy, sibling order, and cost center.
- [Payroll export document](https://developers.jobhandy.io/api-reference/models/payroll-export-document.md): Payroll export metadata including format, month range, filename, media type, and timestamps.
- [Error response](https://developers.jobhandy.io/api-reference/models/error-response.md): Stable public error envelope containing code, message, and request correlation ID.

### Specification

- [OpenAPI specification](https://developers.jobhandy.io/api-reference/openapi-specification.md): Download the authoritative JobHandy Public API contract in OpenAPI 3.1 JSON or YAML format.

## OpenAPI Specs

- [jobhandy-public-api.openapi](https://assets.jobhandy.io/api-spec/jobhandy-public-api.openapi.json)
- [jobhandy-public-api.openapi](/openapi/jobhandy-public-api.openapi.json)
- [jobhandy-public-api.openapi](/openapi/jobhandy-public-api.openapi.yaml)

> The links below point to documentation indexes. Follow each `/_llms/` index recursively until you reach documentation pages.

## Indexes

- [German (67 pages)](https://developers.jobhandy.io/_llms/de.md): Documentation for German.