> ## 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.
# Documents: overview and lifecycle
> What a document is, its statuses, and the object structure
A document in Doodocs People is an HR order or other act created from a **template**
or from [a PDF you upload](/en/guides/documents/uploads). It has **subjects**
(`subject_employee_ids` — the employees the document is about), a **route** of approval
and signing steps, and a set of **files** (print form, signed PDF, e-signature card).
Working with documents through the Developer API means two sets of scopes:
`documents:read` for reading and downloading files, and `documents:write` for
creating, routing, sending, and signing.
Effective access is the intersection of the key's scopes and the key owner's permission
profile. A scope is necessary but not sufficient: you see only what the key owner's role
sees. A single document unavailable to the key returns the same `404`
`DOCUMENT_NOT_FOUND` as one that does not exist — the response code cannot verify
whether a hidden document exists.
## Lifecycle
A draft is filled in with a route (the status does not change while this happens), then
launched by sending. From there the document goes through approval and/or signing and
reaches completion — or is broken off by a rejection, a change request, or a revocation.
```mermaid theme={null}
%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
[*] --> DRAFT
DRAFT --> ON_APPROVAL: _send
DRAFT --> ON_SIGN: _send
ON_APPROVAL --> ON_SIGN: approved
ON_APPROVAL --> COMPLETED: approved
ON_SIGN --> COMPLETED: signed
ON_APPROVAL --> REJECTED: _reject
ON_SIGN --> REJECTED: _reject
ON_APPROVAL --> CHANGE_REQUESTED: _request_changes
ON_SIGN --> CHANGE_REQUESTED: _request_changes
ON_APPROVAL --> REVOKED: _revoke
ON_SIGN --> REVOKED: _revoke
COMPLETED --> [*]
```
The `status` values live in the `status` field. Survive unfamiliar values — the set may
grow within `v1`.
| `status` | Meaning |
| ---------------------------------- | ------------------------------------------------------------------------- |
| `DOCUMENT_STATUS_DRAFT` | Draft. The route can be set and changed; the document is not launched yet |
| `DOCUMENT_STATUS_ON_APPROVAL` | On approval — the approval step is active |
| `DOCUMENT_STATUS_ON_SIGN` | On signing — the signing step is active |
| `DOCUMENT_STATUS_COMPLETED` | All steps passed, the document is signed and completed |
| `DOCUMENT_STATUS_REJECTED` | Rejected by a route participant |
| `DOCUMENT_STATUS_CHANGE_REQUESTED` | A participant requested changes — the document went back for rework |
| `DOCUMENT_STATUS_REVOKED` | Revoked by the initiator or a manager |
| `DOCUMENT_STATUS_ARCHIVED` | The document is archived |
## The document object
The full object is returned by `GET /documents/{document_id}` — together with files and
the route. The list endpoint `GET /documents` returns only scalar fields (no `files`,
no `route`).
| Field | Type | Meaning |
| ----------------------- | ---------------- | -------------------------------------------------------- |
| `id` | UUID | Document identifier |
| `title` | string | Title |
| `status` | DocumentStatus | Current status (table above) |
| `type_id` | UUID | Document type |
| `initiator_employee_id` | UUID | Initiator — the key owner's employee |
| `subject_employee_ids` | UUID\[] | Document subjects |
| `number` | string | Number (may be empty until assigned) |
| `date` | `YYYY-MM-DD` | Document date |
| `organization_id` | UUID | Organization |
| `department_id` | UUID | Department |
| `files` | File\[] | Document files (see below) |
| `route` | Route | Approval and signing route (see below) |
| `create_time` | RFC 3339 | When it was created |
| `update_time` | RFC 3339 | When it was last changed |
| `completed_at` | RFC 3339 \| null | When it was completed; `null` until the document is done |
### Files
Each element of `files[]` is `{ "file_id": "…", "file_type": "…" }`. Download a file by
type via `GET /documents/{document_id}/download?file_type=…`.
| `file_type` | What it is |
| ------------------- | ----------------------------------------- |
| `FILE_TYPE_PDF` | Signed PDF (the default when downloading) |
| `FILE_TYPE_PREVIEW` | Print form |
| `FILE_TYPE_DDCARD` | E-signature card |
| `FILE_TYPE_DOCX` | Source DOCX |
| `FILE_TYPE_JSON` | JSON representation |
### Route
`route` describes approval and signing: `{ "id", "status", "active", "steps": [] }`.
Each step is a `step_type` (`STEP_TYPE_APPROVAL` or `STEP_TYPE_SIGNING`), a `rule`
(`STEP_RULE_ALL` — all are required, `STEP_RULE_ANY_ONE` — one is enough), and a list of
`participants[]`.
```json theme={null}
{
"id": "8c2d…",
"title": "Employment order — Kulyash Baiseitova",
"status": "DOCUMENT_STATUS_ON_SIGN",
"type_id": "t1…",
"initiator_employee_id": "3f2a9c7e-…",
"subject_employee_ids": ["3f2a9c7e-…"],
"number": "ORD-2026-014",
"date": "2026-02-10",
"organization_id": "org1…",
"department_id": "d1…",
"files": [
{ "file_id": "f1…", "file_type": "FILE_TYPE_PREVIEW" },
{ "file_id": "f2…", "file_type": "FILE_TYPE_PDF" }
],
"route": {
"id": "r1…",
"status": "ROUTE_STATUS_ACTIVE",
"active": true,
"steps": [
{
"step_type": "STEP_TYPE_SIGNING",
"rule": "STEP_RULE_ALL",
"participants": [
{
"id": "p1…",
"employee_id": "9b7f…",
"key_type": "INDIVIDUAL",
"status": "PARTICIPANT_STATUS_PENDING"
}
]
}
]
},
"create_time": "2026-02-10T08:00:00Z",
"update_time": "2026-02-10T09:15:00Z",
"completed_at": null
}
```
Route participants are described only by identifiers: `id`, `employee_id`, `key_type`,
and `status`. The document object contains no names, IINs, or job titles — to get an
employee's data by `employee_id`, read it through the
[employees API](/en/guides/employees/model) with your key.
## Visibility in the list
`GET /documents` shows documents by initiator and by the key owner's permission scope. A
document available to the key only through route participation (a participant grant)
will **not** appear in the list — but `GET /documents/{document_id}` will return it.
Do not rely on the list as a complete registry of visible documents. If you have an
identifier (for example from a webhook), fetch the document directly via
`GET /documents/{document_id}`.
## Next
Find a template and read its `variable_schema`.
Create → route → send → sign → download.
The `document.*` webhooks and reacting to status changes.