Approve a document as a participant

An integrator does not always create documents. Often it acts on the approver’s side: a system of yours decides whether to approve an order or send it back for changes, and it has to do that through the API. Everything below needs the documents:write scope, and reading the document needs documents:read.

A document you can reach only through route participation does not appear in GET /documents: the registry lists by initiator and by permission. Events are therefore the only reliable entry point for this scenario. See Listing documents.

Subscribe to approval events

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{
    "url": "https://your-server/hooks/doodocs",
    "event_types": ["document.approval_started", "document.change_requested", "document.completed"]
  }'

The event carries {"document_id": "…"}, which is all you need to read the document with your own key.

Read the document with its route

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

{
  "document": {
    "id": "8c2d5a91-…",
    "status": "DOCUMENT_STATUS_ON_APPROVAL",
    "route": {
      "is_active": true,
      "steps": [
        {
          "id": "st_1…",
          "index": 0,
          "step_type": "STEP_TYPE_APPROVAL",
          "rule": "STEP_RULE_ALL",
          "status": "STEP_STATUS_ACTIVE",
          "participants": [
            {
              "id": "pt_9f…",
              "employee_id": "3f2a9c7e-…",
              "status": "PARTICIPANT_STATUS_ACTIVE"
            }
          ]
        }
      ]
    }
  }
}

Find your slot

You need the participant whose employee_id matches the key owner’s employee record and whose status is PARTICIPANT_STATUS_ACTIVE. That participant’s id is what an action takes.

def my_active_slot(document: dict, my_employee_id: str) -> str | None:
    for step in document["route"]["steps"]:
        if step["status"] != "STEP_STATUS_ACTIVE":
            continue
        for p in step["participants"]:
            if p["employee_id"] == my_employee_id and p["status"] == "PARTICIPANT_STATUS_ACTIVE":
                return p["id"]
    return None

The Developer API has no “who am I” endpoint. Store the key owner’s employee_id in your integration’s configuration; it stays the same while the owner works in the same organization.

Perform the action

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

Action	Endpoint	Comment	Result
Approve	`_approve`	optional	the step moves on
Reject	`_reject`	required	`DOCUMENT_STATUS_REJECTED`
Request changes	`_request_changes`	required	`DOCUMENT_STATUS_CHANGE_REQUESTED`

Step completion rules

rule decides when a step closes:

STEP_RULE_ALL — every participant of the step must act;
STEP_RULE_ANY_ONE — one is enough, and the remaining slots become PARTICIPANT_STATUS_SKIPPED.

So do not assume your approval closes the step. Re-read the document afterwards, or wait for document.signing_started or document.completed.

Errors worth handling

Situation	What you get
The slot already acted, or the step is not active	`400`, a document state error
A `participant_id` that is not yours	`404` `DOCUMENT_NOT_FOUND`
The document is not accessible to the key	`404` `DOCUMENT_NOT_FOUND`
The key lacks `documents:write`	`403` `DEVELOPER.SCOPE_INSUFFICIENT`

Repeating _approve on a slot that already acted is safe: it returns a state error instead of recording a second approval.

Document events

The full event list and what to do for each.

Signing

When your slot signs rather than approves.

Getting started

Employees

Documents

Recipes

Approve a document as a participant

Step completion rules

Errors worth handling

Next

Document events

Signing

​Step completion rules

​Errors worth handling

​Next

Document events

Signing

Step completion rules

Errors worth handling

Next