v1
latestOpenAPI 3.1.02026-08-066378446.6 KBList documents
<small>Requires an API token with the Document Reader role.</small>
Lists the 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 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 values that have been associated with your documents. To do this, first use the List Metadata 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 |
| 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
Which page of results to return
How many results to return per page. Max is 100
Name of the field to sort the response by. One of: name, stage, created_at, updated_at, archived_at, relevance. In addition to these fields, a metadata name may be given here.
The direction to sort results in. One of: asc, desc
Finds documents with an expiration date in the past. Sending false has no effect.
Text provided here will be used to search various places in the document including the name, plaintext content, metadata, parties, etc. If sort_by is not provided, matching results will be returned in order of relevance.
Comma-separated list of one or more team UUIDs to match. Matches documents that belong to any of the given teams.
Finds documents that are not assigned to any team. May be combined with the teams filter to find documents that are in the given teams or are unassigned. Sending false has no effect.
Comma-separated list of one or more template UUIDs. Matches documents created from any of the given templates.
Comma-separated list of document user names to match. Each name must be in the format "Firstname_Lastname", with the space between the first name and last name replaced with an underscore. Matches documents with any of the given users involved.
Comma-separated list of one or more tag UUIDs to match. The default behavior is to match documents that have any of the given tags.
Changes tags behavior to only match documents that have all of the given tags. Sending false has no effect.
Comma-separated list of one or more tag UUIDs to exclude. Documents with any of these tags will be excluded from the result.
Comma-separated list of one or more document stages. Matches documents that are in any of the given stages.
Comma-separated list of one or more document origins. Matches documents with any of the given origins.
Either has_any or has_open. has_any will find documents that have at least one discussion (regardless of current status). has_open will find only documents that have at least one open discussion.
Response
Paginated set of DocumentMinimalResource
Example response
{
"data": [
{
"uuid": "4df1e60a-0114-4dce-89e7-8c5ad397fcf2",
"name": "Kundenvertrag Muster GmbH",
"locale": "de-AT",
"template_uuid": "4df1e60a-0114-4dce-89e7-8c5ad397fcf2",
"parties": [
{
"uuid": "595703a2-b7f6-4772-a4b7-ab2f9fac3a9f",
"ref_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"reference": "Employer",
"entity_name": "Demo Inc.",
"address": "1 Oxford Road\nHenley Bridge\nHB1 1PQ"
}
],
"links": {
"show": "https:...",
"latest_revision_pdf": "https:...",
"latest_revision_pdf_download": "https:..."
}
}
]
}