---
title: "Filter documents with structured conditions"
method: POST
path: "/v1/documents/filter"
tags: ["Delivery"]
---

# Filter documents with structured conditions

`POST /v1/documents/filter`

## Request

- Base URL: `https://api.talonic.com`
- URL: `https://api.talonic.com/v1/documents/filter`
- Auth: HTTP bearer

Query documents using an ordered list of filter conditions against
materialised field values. Optional free-text `search` applies
alongside the structured filter. `limit` is clamped to a server-side
maximum of 500.

## Request body

- FilterDocumentsRequest
  - `source_id` string, uuid: Optional source connection UUID to narrow the result set.
  - `conditions` FilterCondition[]: Ordered list of filter conditions, ANDed together.
    - `fieldId` string, required: User-schema field id or materialised column identifier.
    - `operator` string, required: Operator identifier (free-form — e.g. `eq`, `contains`, `between`).
    - `value` unknown
    - `valueTo` unknown
  - `search` string: Optional free-text search applied alongside the structured conditions.
  - `sort` FilterSort
    - `fieldId` string, required: Field id to sort by.
    - `direction` 'asc' | 'desc', required: Sort direction.
  - `page` integer: 1-based page number. Default 1.
  - `limit` integer: Page size. Server clamps to a maximum of 500. Default 50.

## Response `200`

Matching documents with a total count.

- FilterDocumentsResponse
  - `data` object[], required: Matching document rows.
  - `total` integer, required: Total number of matching documents.
  - `links` object
    - `self` string

## Other responses

- `400`: The request is invalid.
- `401`: Missing or invalid API key.
- `429`: Daily rate limit exceeded.

---

[API](https://skmtc.dev/talonic/apis/talonic-api.md) · [All operations](https://skmtc.dev/talonic/apis/talonic-api/llms.txt) · [OpenAPI document](https://skmtc.dev/talonic/apis/talonic-api/revisions/678fe5f8c9c3?raw)