Skip to main content
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.
Reading directories and the document requires the documents:read scope, while creating, routing, sending, and signing require documents:write.
1

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

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).
The response is the document with status DOCUMENT_STATUS_DRAFT and its id.
3

Set the signing route

A draft needs a route. For the order, a single signing step assigned to the manager Akhmet Baitursynov is enough.
The document stays in DOCUMENT_STATUS_DRAFT — the route is only described so far.
4

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

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}.
How to get a base64 signature from NCALayer or eGov Mobile is in the signing guide. Here only one thing matters: you pass the ready EDS in signature, and the server validates it.
When the last required step is signed, the document moves to DOCUMENT_STATUS_COMPLETED.
6

Download the signed PDF

For a completed document, request a presigned link to the final file.
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.

​
Lifecycle

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

​
Next

Signing

NCALayer, eGov Mobile, and producing a base64 EDS.

Document templates

How to read variable_schema and fill in template_values.