List Fields

List canonical fields from the Talonic field registry with cursor pagination, name search, tier filtering, and cluster filtering, with occurrence counts.

The Field Registry is the knowledge graph of all canonical fields discovered across your extracted documents, and GET /v1/fields lists its entries. Every time Talonic processes a document, it maps raw field names to canonical entries in the registry, normalizing variations like inv_num, Invoice Number, and invoice_no into a single canonical field.

Fields carry one of three maturity levels based on extraction frequency: Canonical fields appear consistently across document types and have the highest confidence. Established fields appear regularly but in fewer document types. Provisional fields have been seen only a handful of times and may still be evolving. In API payloads, maturity is expressed as the numeric tier field: 1 = Canonical, 2 = Established, 3 = Provisional.

Each field belongs to a semantic cluster — a group of conceptually related fields discovered through embedding similarity. For example, invoice_number, po_number, and order_id might share a cluster called "identifiers". Clusters help you understand the shape of your data without manually categorizing hundreds of fields.

Use GET /v1/fields to browse, search, and filter the registry. The endpoint supports cursor-based pagination for efficient traversal of large registries, and filtering by maturity level (tier), cluster, and name search.

The Field Registry is read-only via the API. Fields are created and promoted automatically as documents are extracted. Use the platform UI to manually merge, rename, or reclassify fields.

GET/v1/fields

Query parameters

searchstringFilter by canonical_name or display_name (case-insensitive partial match via ILIKE).

tierintegerFilter by maturity level: 1 (Canonical), 2 (Established), or 3 (Provisional).

cluster_idstringFilter by semantic cluster UUID.

limitintegerMaximum number of results to return (1–100). Default: 20

cursorstringPagination cursor from a previous response.

orderstringSort direction by created_at. Default: desc

Response

Response fields

dataarrayArray of field objects.

data[].idstringField UUID.

data[].canonical_namestringNormalized canonical field name (e.g. invoice_number).

data[].display_namestringHuman-readable display name (e.g. Invoice Number).

data[].data_typestringInferred data type (string, number, date, boolean, array).

data[].tierintegerMaturity level: 1 (Canonical), 2 (Established), 3 (Provisional).

data[].cluster_namestringName of the semantic cluster this field belongs to.

data[].occurrence_countintegerTotal number of times this field has been extracted across all documents.

data[].master_instructionstring | nullSynthesized extraction instruction derived from field occurrences.

data[].created_atstringISO 8601 creation timestamp.

data[].updated_atstringISO 8601 last update timestamp.

data[].linksobjectRelated resource URLs.

data[].links.selfstringURL to fetch this field by ID.

data[].links.similarstringURL to find similar fields by embedding similarity.

pagination.totalintegerTotal number of fields matching the query.

pagination.limitintegerMaximum results per page.

pagination.has_morebooleanWhether more results exist beyond this page.

pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "canonical_name": "invoice_number",
      "display_name": "Invoice Number",
      "data_type": "string",
      "tier": 1,
      "cluster_name": "identifiers",
      "occurrence_count": 1847,
      "master_instruction": "Extract the unique invoice identifier, typically alphanumeric, found in the header area of the document.",
      "created_at": "2024-06-15T10:00:00.000Z",
      "updated_at": "2024-12-01T08:30:00.000Z",
      "links": {
        "self": "/v1/fields/f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "similar": "/v1/fields/f1a2b3c4-d5e6-7890-abcd-ef1234567890/similar"
      }
    },
    {
      "id": "a2b3c4d5-e6f7-8901-bcde-f23456789012",
      "canonical_name": "total_amount",
      "display_name": "Total Amount",
      "data_type": "number",
      "tier": 1,
      "cluster_name": "financials",
      "occurrence_count": 1523,
      "master_instruction": "Extract the final total or grand total amount, usually at the bottom of the document after tax and discounts.",
      "created_at": "2024-06-15T10:05:00.000Z",
      "updated_at": "2024-11-28T15:20:00.000Z",
      "links": {
        "self": "/v1/fields/a2b3c4d5-e6f7-8901-bcde-f23456789012",
        "similar": "/v1/fields/a2b3c4d5-e6f7-8901-bcde-f23456789012/similar"
      }
    }
  ],
  "pagination": {
    "total": 342,
    "limit": 20,
    "has_more": true,
    "next_cursor": "eyJpZCI6ImEyYjNjNGQ1LWU2ZjctODkwMS1iY2RlLWYyMzQ1Njc4OTAxMiJ9"
  }
}

Filter by tier

curl -H "Authorization: Bearer tlnc_..." \
  "https://api.talonic.com/v1/fields?tier=1&limit=50"

Errors

Error responses

400validation_errorInvalid tier or cluster_id query parameter value.

401unauthorizedMissing or invalid API key.

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

Field Harmonization

Get Field & Similar Fields

Registry Query

List Schemas