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

# Find and read employees

> Look up employees by our ID or by yours.

Once your employees are in, you can read them back for any date, by our ID or by your own key.

| Call | Returns |
| - | - |
| [Get Employee](https://docs.intermezzo.ai/api-reference/preview/great-britain/get-employee.md) `GET /gb/organizations/{organization_id}/employees/{employee_id}` | The hub and every satellite, each the edition valid today (or the first upcoming one), with its `edition` |
| [List Employees](https://docs.intermezzo.ai/api-reference/preview/great-britain/list-employees.md) `GET /gb/organizations/{organization_id}/employees` | One page of employees, including closed employees |

## Read one employee

Add `?valid_at=` to read the employee as of another date, past or future: for example to check a change you sent for a future date, or to see the data a past payroll used. A satellite with no edition on that date is `null`.

```http Request theme={null}
GET /gb/organizations/{organization_id}/employees/{employee_id}?valid_at=2026-12-15
```

The `edition` of each satellite is the value you send in `If-Match` when you change it (see [Changing data](https://docs.intermezzo.ai/preview/concepts/changing-data.md)).

## List employees

Each item in the list holds the hub with `core`, `job` and `tax` only. Read the employee for the other satellites. The list is paginated (see [Pagination](https://docs.intermezzo.ai/preview/concepts/pagination.md)).

Sort the list with `sort`, for example `sort=-created_at` for the newest first. Keep the same `sort` while you follow the cursors.

## Read an employee by your own key

If you sent an `external_ref` when you created the employee, use it in the path with the `ext:` prefix instead of the `id`:

```http Request theme={null}
GET /gb/organizations/{organization_id}/employees/ext:EMP-100234
```

This works for every employee call, including `PUT` on a satellite (see [Conventions](https://docs.intermezzo.ai/preview/conventions.md#address-a-record-by-your-own-key)). There is no search by name or NI number.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.