---
title: "List documents"
method: GET
path: "/documents"
tags: ["General"]
---

# List documents

`GET /documents`

<small>Requires an API token with the **Document Reader** role.</small>

Lists the [documents](/#documents) available in your account.

## Filtering

The document list can be filtered by a number of different attributes. The available filter attributes are listed
under `filter` in the [Query Parameters](/operations/v1.documents.index#Query-Parameters) section of this page.

To specify filters, use array notation in the request query string to specify one or more `filter` values.

For example, to filter for archived documents with a name that contains the string "Arbeitsvertrag" and that are
in either the `draft` or `review` stages, the query string should contain:

`filter[archived]=true&filter[query]=Arbeitsvertrag&filter[stages]=draft,review`

### Filtering by metadata

In addition to filtering by the static list of attributes that are documented for the `filter` query parameter,
it is also possible to filter by the [metadata](/#metadata) values that have been associated with your documents.
To do this, first use the [List Metadata](/operations/v1.metadata.index) endpoint to find the `name` of the
metadata field you would like to filter by.

Then construct a filter value containing the value you would like to filter for. How exactly to do this depends
on the metadata's `value_type`. The following table shows the possible values for `value_type` and examples of
filter values for each type.

|Value type|Example filter values|
|----------|---------------------|
| `number` | `123,456` (between 123 & 456), `123,123` (exactly 123), `123,` (greater than or equal to 123), `,456` (less than or equal to 456)
| `currency` | Accepts currency code (optional) and numeric value concatenated with a semicolon. e.g. `EUR;1234.56`, `;1234.56`, `1234.56` |
| `currency_duration` | Accepts currency code (optional), numeric value and interval (optional, one of `monthly` or `yearly`) concatenated with a semicolon. e.g. `EUR;1234.56;monthly`, `;1234.56;yearly`, `1234.56` |
| `date` | `2025-01-01,2025-01-31` (between the given dates), `2025-01-01,2025-01-01` (on the given date), `2025-01-01,` (on or after the given date), `,2025-01-31` (on or before the given date) |
| `timestamp` | Same as `date`, but the values may also include a time component: `2025-01-01T11:00:00Z,2025-01-31T23:59:59Z` |
| `bool` | `true` or `false`
| `clause` | Same as `bool`
| `text` | `Example` (matches the value of the field exactly. e.g. `Example` will match `Example` but not `Example text`) |
| `textarea` | Same as `text`
| `email` | Same as `text`
| `select` | Expects a comma-separated string of values from the metadata's `select_values`. e.g. if the field has the select values "One", "Two" and "Three", a filter value of `One,Two` will match any documents with the metadata set to "One" or "Two" |
| `duration` | Accepts a PHP-compatible duration specification. e.g. `P6D` (6 days), `P2W` (2 weeks), `P1Y` (1 year), capable of ranges and exact matches (see number) |

Once you have the name of the metadata and a filter value to filter for, construct the filter parameter for the
query string as follows:

`filter[<metadata_name>]=<filter_value>`

For example, if we have a number-type metadata called `number_of_units` and want to filter for documents where
this metadata has a value between 100 and 200, the query string should contain:

`filter[number_of_units]=100,200`

## Sorting

To specify the order that documents should be returned in, use the `sort_by` and `sort_direction` query string
parameters.

For example, to sort by the `name` attribute in ascending order, the query string should contain:

`sort_by=name&sort_direction=asc`

## Query parameters

- `page` string
- `per_page` string
- `sort_by` string
- `sort_direction` string
- `filter[archived]` string
- `filter[expired]` string
- `filter[query]` string
- `filter[teams]` string
- `filter[team_unassigned]` string
- `filter[templates]` string
- `filter[document_users]` string
- `filter[tags]` string
- `filter[tag_and]` string
- `filter[excluded_tags]` string
- `filter[stages]` string
- `filter[origins]` string
- `filter[discussions]` string

## Response `200`

Paginated set of `DocumentMinimalResource`

- object
  - `data` DocumentMinimalResource[], required
    - `uuid` string, required
    - `name` string, required
    - `origin` 'signed_pdf' | 'signed_pdf_external_account' | 'template' | 'scratch' | 'onboarding' | 'pdf', required
    - `stage` 'draft' | 'approved_draft' | 'review' | 'approved_review' | 'signing' | 'done', required
    - `locale` string, nullable, required
    - `template_uuid` string, required — UUID of the [template](/#templates) the document was created from, if any
    - `created_at` string, date-time, nullable, required
    - `updated_at` string, date-time, nullable, required
    - `archived_at` string, date-time, nullable, required
    - `parties` DocumentPartySnippetResource[], required — The people and/or organizations that will be involved in signing the document
      - `uuid` string, required
      - `ref_uuid` string, required — If the document containing this party was created from a template, this identifier will be the same as the `ref_uuid` of the corresponding party in the source template.
      - `reference` string, nullable, required — A generic reference for the party
      - `entity_name` string, nullable, required — The actual name of the party. May be null if the party was created via a Template's "set later" option
      - `address` string, nullable, required
      - `scope` 'internal' | 'internal_and_external', required
      - `is_internal_party` boolean, required — Indicates whether this party is linked to an account party (internal) or is standalone (external)
      - `is_ready_for_signing` boolean, required — `true` indicates that an external party has indicated they are ready to sign
      - `ready_for_signing_at` string, date-time, nullable, required
      - `created_at` string, date-time, nullable, required
      - `updated_at` string, date-time, nullable, required
    - `links` object, required
      - `show` string, required — Link to [Show document](/operations/v1.documents.show)
      - `latest_revision_pdf` string, required — Link to [show latest revision PDF details](/operations/v1.documents.revisions.latest.pdf.show)
      - `latest_revision_pdf_download` string, required — Link to [download latest revision PDF](/operations/v1.documents.revisions.latest.pdf.download)
  - `links` object, required
    - `first` string, nullable, required
    - `last` string, nullable, required
    - `prev` string, nullable, required
    - `next` string, nullable, required
  - `meta` object, required
    - `current_page` integer, required
    - `from` integer, nullable, required
    - `last_page` integer, required
    - `links` object[], required — Generated paginator links.
      - `url` string, nullable, required
      - `label` string, required
      - `active` boolean, required
    - `path` string, nullable, required — Base path for paginator generated URLs.
    - `per_page` integer, required — Number of items shown per page.
    - `to` integer, nullable, required — Number of the last item in the slice.
    - `total` integer, required — Total number of items being paginated.

## Other responses

- `401` — Unauthenticated
- `403` — Authorization error
- `422` — Validation error

---

[API](https://skmtc.dev/fynk/apis/fynk-api-reference.md) · [All operations](https://skmtc.dev/fynk/apis/fynk-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fynk/fynk-api-reference/revisions/9657a6757f59/schema)