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}. The list is returned newest first.

{
  "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.
`custom_fields`	object	Custom fields by `api_name`. Only with `expand=custom_fields`.

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. The record’s custom fields are also returned only via expand — see Custom fields.

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

Custom fields

Fields the company added to the employee record itself (shirt size, badge number, grade) come in custom_fields with expand=custom_fields. It is an object: the key is the field’s api_name, the value is JSON shaped by the field type. Without expand=custom_fields the object is empty.

curl -H "X-API-Key: ddp_YOUR_KEY" \
  "https://app.doodocs.kz/api/developer/v1/employees/3f2a9c7e-…?expand=custom_fields"

{
  "id": "3f2a9c7e-…",
  "status": "EMPLOYEE_STATUS_ACTIVE",
  "custom_fields": {
    "badge_number": "A-17",
    "shirt_size": "L",
    "languages": ["kk", "ru", "en"],
    "contract_end": "2027-03-01",
    "children": [
      { "name": "Aigerim", "birth_date": "2019-05-01" }
    ]
  },
  "redacted_fields": ["employees.salary_grade"]
}

Field catalog

GET /employee_custom_fields describes the fields: api_name, title, type, options for lists and columns for tables. The title comes in the Accept-Language language when a translation exists. The scope is the same — employees:read.

{
  "custom_fields": [
    {
      "api_name": "shirt_size",
      "title": "Shirt size",
      "description": "",
      "type": "CUSTOM_FIELD_TYPE_SELECT",
      "options": ["S", "M", "L", "XL"],
      "columns": [],
      "create_time": "2026-02-01T06:00:00Z",
      "update_time": "2026-02-01T06:00:00Z"
    }
  ]
}

The catalog and the values follow the same rules: a record carries only keys from the catalog, and the catalog lists only fields whose values the key owner may see on other employees’ records. Fields visible to “System administrators only” are in the catalog only when the key owner is a system administrator.

Value types

`type`	Value JSON
`TEXT`, `MULTILINE_TEXT`, `EMAIL`, `URL`, `PHONE`	string
`NUMBER`, `CURRENCY`, `PERCENTAGE`	number
`DATE`	string `YYYY-MM-DD`
`DATETIME`	string, RFC 3339 in UTC; `YYYY-MM-DD` when only a date was entered
`BOOLEAN`	`true` / `false`; an unticked checkbox has no value
`SELECT`	string, one of `options`
`MULTISELECT`	array of strings from `options`
`LOOKUP`	string — UUID of the referenced record, not expanded
`TABLE`	array of objects keyed by the `api_name` of `columns`

type is shortened in the table: the response carries the CUSTOM_FIELD_TYPE_ prefix. Ignore unknown types — the list will grow.

Good to know

No key, no value. When a field is in the catalog but its key is missing from custom_fields, the value is empty. Fields outside the catalog never appear, even on the key owner’s own record. Fields hidden by permissions may be listed in redacted_fields as employees.<api_name>, but rely on the catalog, not on that list.
Files and images are not returned yet. Fields of these types are absent from both the catalog and the values; such columns are removed from tables too.
Formula (computed) fields are not returned.
Values are not translated. You get the value as it was entered.
No filtering by custom fields. Select employees on your side.
Changes. Editing a value changes the record’s update_time and sends employee.changed, so updated_since picks it up. Changing the field itself (title, options, visibility) does not touch records. The catalog and records are read in separate requests, so a key missing from your copy of the catalog means it is time to re-read the catalog.
Employee record only. Custom fields of the person (person) are not returned yet.

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`)

Custom fields

Field catalog

Value types

Good to know

Access model

Next

Employee graph

Statuses and lifecycle

Pagination

​Fields

​Related objects

​person (expand=person)

​department and job_title

​manager (expand=manager)

​Custom fields

​Field catalog

​Value types

​Good to know

​Access model

​Next

Employee graph

Statuses and lifecycle

Pagination

Fields

Related objects

`person` (`expand=person`)

`department` and `job_title`

`manager` (`expand=manager`)

Custom fields

Field catalog

Value types

Good to know

Access model

Next