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

# Send a document for signing

> Create an order, run it through the route, and get a signed PDF

Let's walk the whole path on a live example: Keruen LLP issues an employment order for
Kulyash Baiseitova, sends it for signing to the manager Akhmet Baitursynov, and downloads the
finished PDF.

<Note>
  Reading directories and the document requires the `documents:read` scope, while
  creating, routing, sending, and signing require `documents:write`.
</Note>

<Steps>
  <Step title="Pick a template">
    Find the active order template and note its `template_id` and `template_version`.
    Take the variable schema (`variable_schema`) for `template_values` from the template
    record — more in the [templates guide](/en/guides/documents/templates).

    ```bash theme={null}
    curl -H "X-API-Key: ddp_YOUR_KEY" \
      "https://app.doodocs.kz/api/developer/v1/document_templates?search=Employment%20order"
    ```
  </Step>

  <Step title="Create the document">
    Assemble the document from the template. The values in `template_values` must conform
    to `variable_schema`, and the order's recipient is set in `subject_employee_ids`. The
    initiator becomes the employee who owns the key (determined by the server, cannot be
    spoofed).

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents \
      -d '{
        "title": "Employment order",
        "type_id": "5c9e…",
        "template_id": "t7…",
        "template_version": 3,
        "template_values": { "position": "HR Manager", "start_date": "2026-03-01" },
        "subject_employee_ids": ["3f2a9c7e-…"]
      }'
    ```

    The response is the document with status `DOCUMENT_STATUS_DRAFT` and its `id`.
  </Step>

  <Step title="Set the signing route">
    A draft needs a route. For the order, a single signing step assigned to the manager
    Akhmet Baitursynov is enough.

    ```bash theme={null}
    curl -X PUT -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/route \
      -d '{
        "steps": [
          { "step_type": "STEP_TYPE_SIGNING", "rule": "STEP_RULE_ALL", "employee_ids": ["9a4f…"] }
        ]
      }'
    ```

    The document stays in `DOCUMENT_STATUS_DRAFT` — the route is only described so far.
  </Step>

  <Step title="Send along the route">
    Launch the route. By default `initial_action` = `SEND_INITIAL_ACTION_SEND_ONLY`: the
    document goes to the signer, and the status moves to `DOCUMENT_STATUS_ON_SIGN`.

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/_send \
      -d '{ "initial_action": "SEND_INITIAL_ACTION_SEND_ONLY" }'
    ```
  </Step>

  <Step title="Sign">
    The signature is always produced on the client side: the server only verifies and
    records it. Akhmet signs with his key through NCALayer (desktop) or eGov Mobile, gets a
    ready base64 CMS/EDS, and passes it to `_sign`.

    `participant_id` is the identifier of the signer's active slot; take it from
    `route.steps[].participants[].id` by reading the document through
    `GET /documents/{id}`.

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/_sign \
      -d '{
        "participant_id": "p1…",
        "signature": "MIIF…base64-CMS…",
        "sign_method": "SIGN_METHOD_NCALAYER"
      }'
    ```

    <Tip>
      How to get a base64 signature from NCALayer or eGov Mobile is in the
      [signing guide](/en/guides/documents/signing). Here only one thing matters: you pass
      the ready EDS in `signature`, and the server validates it.
    </Tip>

    When the last required step is signed, the document moves to
    `DOCUMENT_STATUS_COMPLETED`.
  </Step>

  <Step title="Download the signed PDF">
    For a completed document, request a presigned link to the final file.

    ```bash theme={null}
    curl -H "X-API-Key: ddp_YOUR_KEY" \
      "https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/download?file_type=FILE_TYPE_PDF"
    ```

    The response is a temporary link to the signed PDF. Other representations are
    available via `file_type`: `FILE_TYPE_PREVIEW` (print form), `FILE_TYPE_DDCARD`
    (e-signature card), `FILE_TYPE_DOCX`, `FILE_TYPE_JSON`.
  </Step>
</Steps>

## Lifecycle

```
DRAFT ──set route──▶ DRAFT ──_send──▶ ON_SIGN ──last step signed──▶ COMPLETED
```

Rejection moves the document to `DOCUMENT_STATUS_REJECTED`, a change request to
`DOCUMENT_STATUS_CHANGE_REQUESTED`, and a revocation by the initiator to
`DOCUMENT_STATUS_REVOKED`.

## Learning about completion

To avoid polling the status, subscribe to the `document.completed` event and download the
PDF on the fact. Document events arrive for every document in the tenant and carry only
`document_id` and timings — not the contents; access is still checked by
`GET /documents/{id}`.

```bash theme={null}
curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{ "url": "https://keruen.example/hooks/doodocs", "event_types": ["document.completed"] }'
```

## Next

<Columns cols={2}>
  <Card title="Signing" icon="pen-nib" href="/en/guides/documents/signing">
    NCALayer, eGov Mobile, and producing a base64 EDS.
  </Card>

  <Card title="Document templates" icon="file-lines" href="/en/guides/documents/templates">
    How to read `variable_schema` and fill in `template_values`.
  </Card>
</Columns>