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

> The employee as a graph node: relationships and traversal via expand

An employee is a node in the org-structure graph. Edges run from it to the department,
job title, manager, organization, location, and the person themselves (`person`). A
manager is also an employee, so the `manager` chain leads further up the hierarchy.

<Frame caption="The employee at the center of the graph, edges being the record's foreign keys">
  ```mermaid theme={null}
  %%{init: {'theme':'neutral'}}%%
  erDiagram
      EMPLOYEE ||--o| PERSON : "person"
      EMPLOYEE ||--o| DEPARTMENT : "department_id"
      EMPLOYEE ||--o| JOB_TITLE : "job_title_id"
      EMPLOYEE ||--o| ORGANIZATION : "organization_id"
      EMPLOYEE ||--o| LOCATION : "location_id"
      EMPLOYEE ||--o| EMPLOYEE : "manager_id"
      EMPLOYEE {
          uuid id
          uuid department_id FK
          uuid job_title_id FK
          uuid organization_id FK
          uuid location_id FK
          uuid manager_id FK
      }
  ```
</Frame>

## Traversal via expand

By default the record carries only `*_id` references. To get a related object in the
same response, list it in `expand`.

* Allowed values: `person`, `department`, `job_title`, `manager`. Any other name gives
  `DEVELOPER.INVALID_EXPAND`.
* Expansion is **flat, one level deep**. There is no nested traversal: you cannot
  request the manager's manager in a single `expand`.
* A comma does **not** separate values — `expand=department,manager` is treated as one
  name. Repeat the parameter for multiple objects.

```bash theme={null}
curl -H "X-API-Key: ddp_YOUR_KEY" \
  "https://app.doodocs.kz/api/developer/v1/employees/3f2a9c7e-…?expand=department&expand=manager"
```

```json theme={null}
{
  "id": "3f2a9c7e-…",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "department_id": "d1c4…",
  "manager_id": "8c5d…",
  "department": {
    "id": "d1c4…",
    "title": "HR Department"
  },
  "manager": {
    "id": "8c5d…",
    "full_name": "Akhmet Baitursynov"
  },
  "redacted_fields": []
}
```

<Warning>
  `manager` is a narrow `ManagerRef` reference: only `id` and a display name, without the
  manager's personal data. To learn the manager's department or IIN, request them as an
  employee — `GET /employees/{manager_id}` — and expand the relationships you need there
  (within your access).
</Warning>

<Note>
  **HRQL under the hood.** The graph and list filters are resolved by our own query
  engine, HRQL — a language akin to where-clauses over the org model. You never write
  HRQL yourself: publicly you work with typed filters and `expand`, and HRQL is what makes
  their traversal efficient. It is an internal engine, not part of the public API.
</Note>

## Next

<Columns cols={2}>
  <Card title="Employee model" icon="user" href="/en/guides/employees/model">
    Record fields and the access model.
  </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">
    List filters and incremental sync.
  </Card>
</Columns>