Documents: overview and lifecycle

A document in Doodocs People is an HR order or other act created from a template or from a PDF you upload. 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.

Document status transitions (DocumentStatus)

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[].

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

Templates

Find a template and read its variable_schema.

Signing

Create → route → send → sign → download.

Events

The document.* webhooks and reacting to status changes.

Getting started

Employees

Documents

Recipes

Documents: overview and lifecycle

Lifecycle

The document object

Files

Route

Visibility in the list

Next

Templates

Signing

Events

​Lifecycle

​The document object

​Files

​Route

​Visibility in the list

​Next

Templates

Signing

Events

Lifecycle

The document object

Files

Route

Visibility in the list

Next