---
title: "Get a list of documents"
method: GET
path: "/documents"
tags: ["Documents"]
---

# Get a list of documents

`GET /documents`

Gets a paginated and filtered list of documents.

This endpoint supports cursor-based pagination. To fetch several pages of documents, repeat the following steps:

1. fetch a page of documents, without specifying a cursor value,
2. if there's a next page, the response will contain a non-empty `cursor` value:

    ```json
    {
      "documents": [...],
      "pagination_meta": {
        "cursor": "c3RyaW5nCg"
      }
    }
    ```

3. make a subsequent `GET /v3/documents` request while including a parameter `cursor=c3RyaW5nCg`, e.g.

    ```json
    GET /v3/documents?cursor=c3RyaW5nCg
    ```

Repeat steps 2 and 3 until you fetch all documents. Use `page_size` parameter to control the number of items in the response list.

## Query parameters

- `context[]` string[]
- `full` boolean
- `title` string
- `states[]` string[]
- `types[]` string[]
- `tags[]` string[]
- `owned` boolean
- `cursor` string, byte
- `signed_at_lt` string, date-time
- `signed_at_gte` string, date-time
- `updated_at_lt` string, date-time
- `updated_at_gte` string, date-time
- `page_size` integer
- `sort_column` 'created_at' | 'updated_at' | 'title'
- `sort_direction` 'asc' | 'desc'
- `integration_object_id` string, string
- `workspace_id` string

## Response `200`

Paginated list of documents

- DocumentIndexResponse — Paginated list of documents
  - `documents` object[]
    - `active_task_count` integer — Number of active tasks
    - `comment_count` integer — Number of comments
    - `completed_task_count` integer — Number of completed tasks
    - `created_at` string, date-time — Date and time the document was created
    - `data_fields` DataField[] — Data fields in this document. Included only when requested with `full=true`.
      - `config` object, required — Additional config for this data field. Contains `options` for `select`, or `label` for `checkbox`.
        - `label` string, nullable
        - `options` string[]
      - `description` string, nullable, required — Description
      - `formatting` object, nullable, required — Formatting
        - `fractional` boolean, nullable
        - `grouping` '' | 'dot' | 'comma' | 'space', nullable
      - `id` string, uuid, required — Unique ID
      - `name` string, required — Name
      - `required` boolean, required — Whether this data field must be filled to send the document for signature
      - `source` 'drafter_questionnaire' | 'ai' | 'salesforce', nullable, required — Source of data for this data field
      - `source_mapping` string, nullable, required — Integration data mapping for this data field. Revealed only when connected to the same integration instance.
      - `source_sync_type` 'downstream' | 'upstream' | 'bidirectional', nullable, required — Integration sync mode for this data field. Revealed only when connected to the same integration instance.
      - `type` 'text' | 'number' | 'date' | 'select' | 'checkbox', required — Type
      - `value` string, nullable, required — Value
    - `folders` object[] — List of folders where the document is present
      - `accessible_by_current_user` boolean — Whether the folder is accessible to the current user or not
      - `email` string, email — Folder's creator email
      - `id` union, required — Folder ID
        - string, uuid
        - 'root'
      - `shared` boolean — Whether the folder is shared or not
      - `title` string — Folder title
    - `id` string, uuid — Document ID
    - `ocr_status` 'none' | 'not_started' | 'pending' | 'success' | 'failure', nullable — OCR status of the document
    - `owner` object — Document's owner information
      - `email` string, email, required — Owner's email address
      - `full_name` string, required — Owner's full name
      - `id` string, uuid, required — Owner's profile ID
    - `parties` object[] — Parties and signees
      - `address` string, nullable — Address
      - `id` string, uuid, nullable — Unique ID
      - `name` string, nullable — Name
      - `number` string, nullable — Company's VAT number or CVR
      - `reference` string, nullable — How the party will be referred to in the document
      - `signees` object[] — Party's signees
        - `changes_requested_at` string, date-time, nullable — Date and time when the signee requested changes to the document
        - `email` string, email, nullable — Signee's email address
        - `full_name` string, nullable — Signee's full name
        - `id` string, uuid, nullable — Unique ID
        - `opened_at` string, date-time, nullable — Date and time when the signee opened the document
        - `order` integer — Signee's signing order. When the signing order mode is set to `grouped`, then this number represents the signee's group number.
        - `rejected_at` string, date-time, nullable — Date and time when the signee rejected the document
        - `signature_verification_methods` string[], nullable — List of allowed signature types for the signee
        - `signed_at` string, date-time, nullable — Date and time when the signee signed the document
        - `title` string, nullable — Signee's title
      - `type` 'personal' | 'company' — Type
    - `sample` boolean — Whether this document exists for demonstration purposes or not
    - `signed_at` string, date-time, nullable — Date and time the document was signed
    - `signing_order_mode` 'random' | 'strict' | 'grouped' — The signing order mode. When it's set to grouped, each signee in `parties.signees`, should have the order field set to the group's number starting from 0.
    - `state` 'draft' | 'rejected' | 'changes_requested' | 'pending' | 'signed' | 'irrelevant' — Document state
    - `tags` string[], nullable — Document's tags
    - `title` string — Document title
    - `to_be_signed_by` 'owner_and_others' | 'others_only' | 'owner_only' — Who should sign the document
    - `type` 'draft' | 'contract' | 'stored_contract' — Document type
    - `updated_at` string, date-time — Date and time the document was last modified
    - `version` string, uuid, nullable — Version
    - `visibilities` object[] — Document's users visibilities
      - `email` string, email, required — Email address
      - `full_name` string, required — Full name
      - `role` 'owner' | 'manager' | 'editor' | 'filler' | 'reviewer', required — Role
    - `workspace` object, nullable — Information about the workspace the document is present in
      - `id` string, uuid — Workspace ID
      - `name` string — Workspace name
      - `permissions` string[] — List of permissions of the current user for the workspace
  - `pagination_meta` object — Pagination metadata
    - `cursor` string, base64, nullable — Identifier of the next page

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Unprocessable request

---

[API](https://skmtc.net/contractbook/apis/contractbook-api.md) · [All operations](https://skmtc.net/contractbook/apis/contractbook-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/contractbook/contractbook-api/revisions/ae9d64e51a99/schema)