Employee 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}.

{
  "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.
`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.

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.

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 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:

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

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.

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.

Employee graph

Employee relationships and traversal via expand.

Statuses and lifecycle

EmployeeStatus values and transitions.

Pagination

Paging through lists and incremental sync.

Getting started

Employees

Documents

Recipes

Fields

`person` (`expand=person`)

`department` and `job_title`

`manager` (`expand=manager`)

Access model

Next

Employee graph

Statuses and lifecycle

Pagination

​Fields

​Related objects

​person (expand=person)

​department and job_title

​manager (expand=manager)

​Access model

​Next

Employee graph

Statuses and lifecycle

Pagination

Fields

Related objects

`person` (`expand=person`)

`department` and `job_title`

`manager` (`expand=manager`)

Access model

Next