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

# Employee model

> The canonical employee record: fields, redacted_fields, and the access model

The employee (`Employee`) is the central API resource. It is a person's record in a
specific tenant: scalar fields and references to related entities. Fetch it as a
list with `GET /employees` or one at a time with `GET /employees/{employee_id}`.

```json theme={null}
{
  "id": "3f2a9c7e-…",
  "employee_number": "HR-014",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "department_id": "d1c4…",
  "job_title_id": "7b2e…",
  "organization_id": "a90f…",
  "location_id": null,
  "manager_id": "8c5d…",
  "work_email": "kulyash@keruen.kz",
  "start_date": "2024-03-01",
  "end_date": null,
  "create_time": "2024-03-01T04:00:00Z",
  "update_time": "2026-02-10T09:30:00Z",
  "redacted_fields": []
}
```

## Fields

| Field             | Type      | Description                                                                                        |
| ----------------- | --------- | -------------------------------------------------------------------------------------------------- |
| `id`              | UUID      | The employee's identifier within the tenant.                                                       |
| `employee_number` | string    | Personnel number. May be empty.                                                                    |
| `status`          | enum      | Lifecycle status (`EmployeeStatus`). See [Statuses and lifecycle](/en/guides/employees/lifecycle). |
| `department_id`   | UUID      | Department. The department object itself comes via `expand=department`.                            |
| `job_title_id`    | UUID      | Job title. The object comes via `expand=job_title`.                                                |
| `organization_id` | UUID      | The legal entity the employee belongs to.                                                          |
| `location_id`     | UUID      | Location. May be `null`.                                                                           |
| `manager_id`      | UUID      | Manager. The `manager` reference (id + name) comes via `expand=manager`.                           |
| `work_email`      | string    | Work email.                                                                                        |
| `start_date`      | date      | Start date (`YYYY-MM-DD`).                                                                         |
| `end_date`        | date      | End date. `null` while the employee is not terminated.                                             |
| `create_time`     | RFC 3339  | When the record was created (UTC).                                                                 |
| `update_time`     | RFC 3339  | When the record was last changed. `updated_since` works off this.                                  |
| `redacted_fields` | string\[] | Fields hidden by the key owner's permissions, in `object.field` form.                              |

<Note>
  Identifiers are UUID strings, timestamps are RFC 3339 in UTC, and calendar dates are
  `YYYY-MM-DD`. Absent values are present in the response (an empty string or `null`)
  rather than dropped from the object. Ignore unfamiliar fields and `enum` values — the
  response shape grows additively.
</Note>

## Related objects

The `person`, `department`, `job_title`, and `manager` fields are separate entities,
available only on request via `expand`. The base response does not include them, only
the `*_id` references. How to traverse these relationships is on the
[Employee graph](/en/guides/employees/graph) page.

### `person` (`expand=person`)

| Field                                    | Type   | Description                                                     |
| ---------------------------------------- | ------ | --------------------------------------------------------------- |
| `first_name`, `last_name`, `middle_name` | string | Name parts                                                      |
| `full_name`                              | string | Ready-to-display full name                                      |
| `iin`                                    | string | IIN. Hidden by permissions → `redacted_fields: ["persons.iin"]` |
| `birth_date`                             | date   | Date of birth (`YYYY-MM-DD`)                                    |
| `phone`                                  | string | Personal phone                                                  |
| `personal_email`                         | string | Personal email                                                  |

### `department` and `job_title`

Both objects are minimal references: `id` + `title`. There are no other fields
(department head, hierarchy, headcount) in them.

### `manager` (`expand=manager`)

A reference to the manager: `id` + `full_name`. This object is deliberately
narrow — to get the manager's full profile, request
`GET /employees/{manager.id}` with your key, so permissions and field redaction
apply to it.

## Access model

Even with the `employees:read` scope, a key does not see everything. **Effective
access is the intersection of the key's scopes and the key owner's permissions.** A
scope is necessary but not sufficient: employees and fields unavailable to the owner's
permission profile stay invisible to the key.

Fields the owner is not allowed to see (for example the IIN) are dropped from the
response, and their keys are listed in `redacted_fields` in `object.field` form. So,
with `expand=person` but without the permission for the IIN:

```json theme={null}
{
  "id": "3f2a9c7e-…",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "person": {
    "first_name": "Kulyash",
    "last_name": "Baiseitova",
    "full_name": "Kulyash Baiseitova"
  },
  "redacted_fields": ["persons.iin"]
}
```

<Warning>
  A field being absent from `redacted_fields` and an empty value are different things. A
  field in `redacted_fields` means "hidden by permissions"; an empty value with no entry
  in `redacted_fields` means "no data." Do not confuse them when syncing.
</Warning>

<Note>
  A single record is indistinguishable by reason of unavailability: "does not exist," "no
  access," and "draft/deleted" all return the same `404` `EMPLOYEE_NOT_FOUND`. The
  response code cannot tell you whether an employee hidden from you exists.
</Note>

## Next

<Columns cols={2}>
  <Card title="Employee graph" icon="diagram-project" href="/en/guides/employees/graph">
    Employee relationships and traversal via `expand`.
  </Card>

  <Card title="Statuses and lifecycle" icon="chart-line" href="/en/guides/employees/lifecycle">
    `EmployeeStatus` values and transitions.
  </Card>

  <Card title="Pagination" icon="layer-group" href="/en/api-reference/pagination">
    Paging through lists and incremental sync.
  </Card>
</Columns>