> ## Documentation Index
> Fetch the complete documentation index at: https://developers.jobhandy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JobHandy Public API

> Build secure, production-grade HR and payroll integrations with the JobHandy Public API.

<Badge color="green" shape="pill" icon="circle-check">Production</Badge> <Badge color="blue" shape="pill" icon="braces">REST + JSON</Badge> <Badge color="purple" shape="pill" icon="file-code">OpenAPI 3.1</Badge>

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.

<Columns cols={3}>
  <Card title="Production base URL" icon="globe">
    `https://api.jobhandy.io/v1`
  </Card>

  <Card title="Authentication" icon="key-round">
    `X-API-Key` on every protected request
  </Card>

  <Card title="Request correlation" icon="hash">
    UUID v4 or v7 in `X-Request-ID`
  </Card>
</Columns>

<CardGroup cols={2}>
  <Card title="Create an API key" icon="key" href="/get-started/api-key-management">
    Create a scoped credential in the JobHandy administration portal.
  </Card>

  <Card title="Start the quickstart" icon="rocket" href="/get-started/quickstart">
    Verify connectivity, authenticate, read employees, and validate a write.
  </Card>

  <Card title="Browse API reference" icon="braces" href="/api-reference/overview">
    Review every operation, parameter, response, schema, and error case.
  </Card>

  <Card title="Download OpenAPI" icon="download" href="/api-reference/openapi-specification">
    Use the authoritative OpenAPI 3.1 contract in JSON or YAML format.
  </Card>
</CardGroup>

## Integration context

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    HRIS[HRIS / HCM] --> INT[Customer integration]
    PAY[Payroll system] --> INT
    IP[Integration platform] --> INT

    INT -->|X-API-Key| API[JobHandy Public API]
    INT -.->|X-Tenant-ID when needed| API
    INT -.->|X-Request-ID recommended| API

    API --> EMP[Employees]
    API --> ORD[Orders]
    API --> INC[Incidents]
    API --> DIV[Divisions]
    API --> EXP[Payroll exports]
```

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

<Columns cols={3}>
  <Card title="Employee synchronization" icon="users" href="/guides/sync-employees">
    Create employees, update supported fields, assign divisions, and block or unblock accounts.
  </Card>

  <Card title="HR order review" icon="badge-check" href="/guides/process-orders">
    Retrieve orders under review and record an approval or rejection decision.
  </Card>

  <Card title="Incident reporting" icon="triangle-alert" href="/guides/manage-incidents">
    Create and update employee incidents and upload permitted supporting files.
  </Card>

  <Card title="Organization structure" icon="network" href="/guides/manage-divisions">
    Create and maintain tenant-owned division hierarchies and cost centers.
  </Card>

  <Card title="Payroll retrieval" icon="file-spreadsheet" href="/guides/payroll-exports">
    Discover payroll export metadata and download available files.
  </Card>

  <Card title="Operational monitoring" icon="heart-pulse" href="/api-reference/health/get-health">
    Check basic public API availability without an API key.
  </Card>
</Columns>

## Core rules

<AccordionGroup>
  <Accordion title="Production endpoint only" defaultOpen icon="server">
    Public integrations use `https://api.jobhandy.io/v1`. Internal development or stage hosts are not part of the public contract.
  </Accordion>

  <Accordion title="Least-privilege access" icon="shield-check">
    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.
  </Accordion>

  <Accordion title="Dry run is not a sandbox" icon="flask-conical">
    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.
  </Accordion>

  <Accordion title="Unknown fields are rejected" icon="braces">
    Request schemas are closed. Send only documented properties and media types.
  </Accordion>

  <Accordion title="Request IDs are not idempotency keys" icon="hash">
    `X-Request-ID` correlates requests and responses. It does not deduplicate writes or make a retry safe.
  </Accordion>
</AccordionGroup>

## Resource model

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart TD
    KEY[API key scope] --> TEN[Tenant / company]
    TEN --> DIV[Divisions]
    TEN --> EMP[Employees]
    EMP --> ORD[Orders]
    EMP --> INC[Incidents]
    ORD --> OA[Order attachments]
    INC --> IA[Incident attachments]
    TEN --> PE[Payroll export documents]
```

See [Architecture and resource model](/concepts/architecture-resource-model) for ownership, relationships, and terminology.

## Recommended path to production

<Steps>
  <Step title="Create a dedicated API key">
    Select only the companies and divisions required by the integration.
  </Step>

  <Step title="Complete the quickstart">
    Verify health, authentication, tenant selection, request IDs, and dry-run validation.
  </Step>

  <Step title="Implement one integration guide">
    Follow the matching employee, order, incident, division, or payroll workflow.
  </Step>

  <Step title="Complete the go-live checklist">
    Validate secret storage, retries, reconciliation, monitoring, and support readiness.
  </Step>
</Steps>

<Card title="Review the go-live checklist" icon="clipboard-check" horizontal href="/get-started/go-live-checklist">
  Confirm that the integration is safe to operate before enabling production schedules.
</Card>