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

# Listing documents

> The GET /documents filters and what the list leaves out

`GET /documents` returns the documents visible to the key owner in the registry,
newest first. The scope is `documents:read`.

List items carry only the document's scalar fields: `files` and `route` are omitted,
so call `GET /documents/{document_id}` for those.

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?status=DOCUMENT_STATUS_ON_SIGN&limit=50"
```

```json theme={null}
{
  "documents": [
    {
      "id": "8c2d5a91-…",
      "title": "Employment order",
      "status": "DOCUMENT_STATUS_ON_SIGN",
      "type_id": "5c9e1f04-…",
      "initiator_employee_id": "3f2a9c7e-…",
      "subject_employee_ids": ["b7e41c2d-…"],
      "number": "PR-000142",
      "date": "2026-02-10",
      "organization_id": "a90f…",
      "create_time": "2026-02-10T09:30:00Z",
      "update_time": "2026-02-10T10:05:00Z"
    }
  ],
  "next_page_token": "CgYIyAE.7f3a"
}
```

## Filters

| Parameter               | Meaning                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------- |
| `status`                | A single `DocumentStatus` value, such as `DOCUMENT_STATUS_ON_SIGN`                              |
| `type_id`               | A document type from the [type catalog](/en/guides/documents/types)                             |
| `initiator_employee_id` | Who created the document                                                                        |
| `created_after`         | Creation date at or after this `YYYY-MM-DD`                                                     |
| `created_before`        | Creation date at or before this `YYYY-MM-DD`                                                    |
| `search`                | Case-insensitive match against the title or the number                                          |
| `updated_since`         | Documents changed at or after this RFC 3339 instant                                             |
| `order_by`              | Order: newest created first by default, `DOCUMENT_ORDER_UPDATED_AT_ASC` for oldest change first |

`status` takes exactly one value: to collect documents in two statuses, make two
requests. Pagination is the shared one, through `limit` and `page_token`; there is no
`total_count` here.

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?type_id=5c9e1f04-…&created_after=2026-02-01&created_before=2026-02-29&search=employment"
```

## What the list leaves out

<Warning>
  A document you can reach **only** through route participation — you are a signer or
  an approver, but not the initiator and you hold no permission over it — never appears
  in this list. The registry lists by initiator and by permission scope, and
  participation is neither. `GET /documents/{id}` on such a document still works.
</Warning>

So an integrator who only participates needs a different entry point: subscribe to
`document.approval_started` and `document.signing_started` and keep the `document_id`
from those events. The recipe
[Approve a document as a participant](/en/guides/recipes/approve-as-participant)
walks through it.

## What to use instead of polling

Polling the list does not replace events: a document can move through several statuses
between two polls. Keep the list for reconciliation and reporting, and build your
reactions on [document events](/en/guides/documents/events).

## Reconciling after downtime

If webhooks were not arriving, fetch everything that changed since the last
successful delivery:

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?updated_since=2026-02-10T09:00:00Z&order_by=DOCUMENT_ORDER_UPDATED_AT_ASC&limit=1000"
```

The `DOCUMENT_ORDER_UPDATED_AT_ASC` order matters: a document that changes mid-walk
moves ahead of your checkpoint instead of slipping past it. Advance the checkpoint by
the `update_time` of the last record you processed.

<Note>
  Encode a timezone offset in the query as `%2B05:00`, or send the time in `Z` (UTC):
  a `+` in a URL is otherwise read as a space.
</Note>