Signing a document

Here is the full path from a template to a signed PDF. Every step except downloading requires the documents:write scope; downloading requires documents:read. One principle matters more than the rest: you produce the signature yourself. The server never signs on your behalf — you send a ready base64 CMS/EDS block, created on the client side with the owner’s key, and the server verifies and records it.

The order of calls: from creation to a signed PDF

Create a document from a template

POST /documents creates a draft from a template. The initiator is set by the server as the key owner’s employee — it cannot be spoofed.

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 — Kulyash Baiseitova",
    "type_id": "t1…",
    "template_id": "tpl_7c1a…",
    "template_version": 3,
    "template_values": {
      "employee_full_name": "Kulyash Baiseitova",
      "position": "HR Manager",
      "start_date": "2026-02-10"
    },
    "subject_employee_ids": ["3f2a9c7e-…"]
  }'

The response is the created document with status DOCUMENT_STATUS_DRAFT. The number, date, and organization_id fields can be passed explicitly; otherwise they are set by the tenant’s rules.

Set the route

PUT /documents/{document_id}/route sets the approval and signing steps. Each step is a step_type, a rule, and a list of employee_ids.

curl -X PUT -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d…/route \
  -d '{
    "steps": [
      { "step_type": "STEP_TYPE_APPROVAL", "rule": "STEP_RULE_ANY_ONE", "employee_ids": ["mgr_ax…"] },
      { "step_type": "STEP_TYPE_SIGNING",  "rule": "STEP_RULE_ALL",     "employee_ids": ["9b7f…"] }
    ]
  }'

step_type is STEP_TYPE_APPROVAL (approval) or STEP_TYPE_SIGNING (signing). rule is STEP_RULE_ALL (all participants required) or STEP_RULE_ANY_ONE (one is enough). The document stays in DRAFT — the route is not launched yet. On an already-launched document, unpassed steps are edited with POST /documents/{document_id}/route/_modify.

Send along the route

POST /documents/{document_id}/_send launches the route: DRAFT moves to ON_APPROVAL or ON_SIGN.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d…/_send \
  -d '{ "initial_action": "SEND_INITIAL_ACTION_SEND_ONLY" }'

initial_action defaults to SEND_INITIAL_ACTION_SEND_ONLY — just send. The values …_APPROVE_FIRST_STEP and …_SIGN_FIRST_STEP immediately close the first step on behalf of the initiator (in which case signature and sign_method are passed with them) and are available only to the initiator.

Find your participant_id

Read the document and take the id of your active participant from route.steps[].participants[] — that is what you pass into signing and approval.

curl -H "X-API-Key: ddp_YOUR_KEY" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d…

{
  "route": {
    "steps": [
      {
        "step_type": "STEP_TYPE_SIGNING",
        "participants": [
          { "id": "p1…", "employee_id": "9b7f…", "status": "PARTICIPANT_STATUS_PENDING" }
        ]
      }
    ]
  }
}

Sign

POST /documents/{document_id}/_sign records the signature. signature is a ready base64 CMS/EDS block created on the client side (desktop NCALayer or eGov Mobile). The server verifies and commits it.What exactly to sign. The CMS is formed over the content of the document’s PDF file — the one pinned to the route at send time. Download it via GET /documents/{document_id}/download (file_type=FILE_TYPE_PDF) and sign exactly those bytes. In NCALayer this is the createCMSSignatureFromBase64 method with the PDF content in base64. The server checks the signature against that file’s digests — a CMS over any other content is rejected.

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d…/_sign \
  -d '{
    "participant_id": "p1…",
    "signature": "MIIFx…base64_CMS…",
    "sign_method": "SIGN_METHOD_NCALAYER"
  }'

sign_method is SIGN_METHOD_NCALAYER or SIGN_METHOD_EGOV_MOBILE. When the last required step is signed, the document moves to DOCUMENT_STATUS_COMPLETED.

The signature is produced on the client side with the owner’s key — the server does not create it. The private key and CMS/EDS generation stay with you; only the ready base64 block travels to the API. Do not send the private key to the server.

Download the signed PDF

GET /documents/{document_id}/download returns a temporary link to the file. file_type defaults to FILE_TYPE_PDF — the signed PDF.

curl -H "X-API-Key: ddp_YOUR_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents/8c2d…/download?file_type=FILE_TYPE_PDF"

{ "url": "https://storage.doodocs.kz/…/signed.pdf?X-Amz-Signature=…" }

Other file types — FILE_TYPE_PREVIEW (print form), FILE_TYPE_DDCARD (e-signature card), FILE_TYPE_DOCX, FILE_TYPE_JSON.

Approve, reject, request changes, revoke

Besides signing, a participant acts on their own active slot — participant_id is taken from the same route.steps[].participants[].id.

Endpoint	Action
`POST /documents/{id}/_approve`	Approve the step. Body: `participant_id`, `comment`? (optional)
`POST /documents/{id}/_reject`	Reject → `REJECTED`. Body: `participant_id`, `comment` (required)
`POST /documents/{id}/_request_changes`	Request changes → `CHANGE_REQUESTED`. Body: `participant_id`, `comment` (required)
`POST /documents/{id}/_revoke`	Revoke a document in progress → `REVOKED`. Available to the initiator or a manager

curl -X POST -H "X-API-Key: ddp_YOUR_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d…/_approve \
  -d '{ "participant_id": "p1…", "comment": "Approved" }'

_approve, _reject, and _request_changes act on the caller’s active slot. To find out which step is active now and what your participant_id is, re-read the document through GET /documents/{document_id}.

Templates

How to read variable_schema before creating.

Events

Catch document.completed instead of polling the status.

Getting started

Employees

Documents

Recipes

Approve, reject, request changes, revoke

Next

Templates

Events

​Approve, reject, request changes, revoke

​Next

Templates

Events

Approve, reject, request changes, revoke

Next