Filter Documents

Search and filter documents by extracted field values via API. Compose equality, comparison, range, containment, and emptiness conditions in one call.

The POST /v1/documents/filter endpoint lets you search documents by their extracted field values: compose conditions on any field Talonic has extracted (supplier names, invoice dates, contract amounts) and get back the matching documents with their field values. Each condition targets a specific field and applies an operator to test its value; multiple conditions are AND-combined. The endpoint also supports free-text search across document content and sorting by any field.

Each condition's fieldId identifies the field to test. Use the field autocomplete endpoint to discover the field IDs available in your workspace; an unresolvable field ID returns a 400 error.

POST/v1/documents/filter

Body parameters

source_idstringScope to a specific source connection.

conditionsarrayArray of filter conditions, AND-combined. Each has fieldId, operator, and optional value / valueTo.

searchstringFree-text search across document content.

sortobjectSort by a field: { fieldId, direction: "asc" | "desc" }.

pageintegerPage number. Default: 1

limitintegerResults per page (max 500). Default: 50

Operators: eq, neq, gt, gte, lt, lte, between, contains, is_empty, is_not_empty

Request body

{
  "conditions": [
    { "fieldId": "fld_a1b2c3d4", "operator": "eq", "value": "Acme Corp" },
    { "fieldId": "fld_e5f6g7h8", "operator": "between", "value": "2024-01-01", "valueTo": "2024-12-31" }
  ],
  "sort": { "fieldId": "fld_e5f6g7h8", "direction": "desc" },
  "page": 1,
  "limit": 25
}

Response

Response fields

dataarrayArray of matching document objects.

data[].idstringDocument UUID.

data[].namestringOriginal filename of the document.

data[].sourceIdstringSource connection ID the document belongs to.

data[].uploadedAtstringISO 8601 ingestion timestamp.

data[].fieldValuesobjectKey-value map of extracted field values for this document.

totalintegerTotal number of documents matching all conditions.

links.selfstringLink to this endpoint.

Response

{
  "data": [
    {
      "id": "doc_x9y8z7w6",
      "name": "Invoice-2024-001.pdf",
      "sourceId": "src_m1n2o3p4",
      "uploadedAt": "2024-09-14T10:32:00Z",
      "fieldValues": {
        "supplier_name": "Acme Corp",
        "invoice_date": "2024-06-15"
      }
    }
  ],
  "total": 47,
  "links": {
    "self": "/v1/documents/filter"
  }
}

Errors

Error responses

400validation_errorA field name in conditions or sort could not be resolved to a registry field.

401unauthorizedMissing or invalid API key.

429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Build conditions programmatically by first calling GET /v1/search/autocomplete to resolve field IDs, then GET /v1/search/field-values to populate value pickers. The response includes the full fieldValues map per document, so you can render result tables without additional per-document fetches.

Filter Documents

Response

Errors

Related