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

# Conventions

> Versioning, formats, filters, and compatibility

## Versioning and compatibility

The version lives in the path: `/developer/v1`. Within a version, only additive
changes are possible — new fields, new enum values, new endpoints.

Your integration must tolerate them without breaking:

* ignore unknown fields in responses;
* survive unknown `enum` values (for example a new employee status);
* do not rely on field order.

Breaking changes ship only under a new major version in the path, with a deprecation
window of at least six months.

## Formats

* Request and response bodies are UTF-8 JSON, with field names in `snake_case`.
* Identifiers are UUID strings.
* Instants are RFC 3339 in UTC (`2026-02-10T09:00:00Z`).
* Calendar dates are `YYYY-MM-DD`.
* Missing values are present in the response (an empty string or `null`); the
  response shape is stable.

## Filters and expand

Filters are passed as query parameters. For multiple values, repeat the parameter:

```
?status=EMPLOYEE_STATUS_ACTIVE&status=EMPLOYEE_STATUS_LEAVE
```

A comma does **not** separate values — `?status=A,B` is read as a single value. The
same rule applies to `expand` and `department_id`.

`expand` loads related objects. Allowed values are `person`, `department`,
`job_title`, `manager`; anything else returns `DEVELOPER.INVALID_EXPAND`. The
`manager` object is deliberately narrow — identifiers and a display name only, with
no personal data about the manager.

## Rate limits

Requests are rate-limited per key. On exceeding the limit you get a `429`; retry with
exponential backoff.

## Visibility

Onboarding drafts (internal status `CREATED`) and deleted employees are never
returned through the Developer API.