> ## 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.

# Employees

> Employee master data, tenant placement, division assignment, account blocking, and synchronization operations.

Employees are customer-scoped master-data resources. The Public API supports list, create, get, and partial update operations.

## Capabilities

| Capability                | Supported | Notes                                         |
| ------------------------- | --------: | --------------------------------------------- |
| List and filter employees |       Yes | Across all key tenants or one selected tenant |
| Create employee           |       Yes | Sends password setup email on real create     |
| Update supported fields   |       Yes | Patch only changed fields                     |
| Change work email         |        No | Not patchable through public update           |
| Move division             |       Yes | Within the same tenant and allowed scope      |
| Transfer tenant           |        No | Not exposed for assigned employees            |
| Block or unblock          |       Yes | Through `blocked`                             |
| Delete employee           |        No | No public delete operation                    |

## Lifecycle

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    A[Resolve tenant and division] --> B[POST dry run]
    B --> C[POST create]
    C --> D[Store JobHandy ID]
    D --> E[GET and PATCH supported fields]
    E --> F[Block or unblock when required]
```

## Endpoints

<CardGroup cols={2}>
  <Card title="List employees" icon="list" href="/api-reference/employees/list-employees">
    Page, filter, sort, and restrict employee collections.
  </Card>

  <Card title="Create an employee" icon="user-plus" href="/api-reference/employees/create-employee">
    Validate placement and create an account.
  </Card>

  <Card title="Get an employee" icon="user" href="/api-reference/employees/get-employee">
    Retrieve one employee by opaque ID.
  </Card>

  <Card title="Update an employee" icon="user-pen" href="/api-reference/employees/update-employee">
    Patch supported fields, division assignment, and blocking state.
  </Card>
</CardGroup>

## Key rules

* Store the JobHandy employee ID after match or create.
* Use a stable customer identifier such as `employeeNumber` where uniqueness is guaranteed.
* Do not use email as the only long-term key unless the customer guarantees immutability.
* Omit patch fields that should remain unchanged.
* Use `null` only for nullable fields that should be cleared.
* Do not use a dry-run preview ID in later requests.

<Card title="Employee synchronization guide" icon="refresh-cw" href="/guides/sync-employees" horizontal>
  Implement identity matching, checkpoints, dry runs, partial updates, and timeout reconciliation.
</Card>