Skip to main content

List Fields

List Field Registry fields with cursor pagination, name search, maturity and cluster filters, and admission and superseded-row controls, 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: Core fields appear consistently across document types and are fully trusted. Proven fields recur and are useful but appear in fewer contexts. Candidate fields are newly discovered and may still be merged, renamed, or expire. Every response names the level in maturity (core, proven, candidate) beside the frozen numeric tier (1, 2, 3).

Two further controls shape what the list returns. admission_state filters on registry admission: the default, canonical, returns admitted fields; provisional returns the provisional pool of not-yet-admitted rows; all disables the filter. Any other value is treated as canonical. include_superseded (default false) controls rows that curation merged into another concept: by default they are hidden, so a cached vocabulary never carries two ids for one concept. A superseded row stays readable by id with superseded_by pointing at the survivor, and every row lists the alternative spellings folded into it in synonyms.

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.
Provisional and superseded rows are hidden by default. GET /v1/fields returns only admission_state=canonical rows and omits rows merged into a survivor. If an integration expects to see every row, pass admission_state=all and include_superseded=true. Stored ids keep working either way: GET /v1/fields/{id} answers for a superseded row with superseded_by, and follow_redirects=true returns the survivor.
GET/v1/fields

Query parameters

searchstringFilter by canonical_name or display_name (case-insensitive partial match via ILIKE).
maturitystringFilter by maturity: core, proven, or candidate. Takes precedence over tier; an unknown value is a 400 invalid_maturity.
tierintegerFrozen numeric maturity filter: 1 (core), 2 (proven), or 3 (candidate). Prefer maturity.
admission_statestringcanonical (admitted fields), provisional (the not-yet-admitted pool), or all (no filter). Other values fall back to canonical. Default: canonical
include_supersededbooleanInclude rows merged into another concept (they carry superseded_by). Default: false
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[].tierintegerFrozen numeric maturity: 1 (core), 2 (proven), 3 (candidate).
data[].maturitystringcore, proven, or candidate.
data[].admission_statestringRegistry admission state, canonical or provisional.
data[].synonymsstring[]Alternative names folded into this field by merges and cleanup (empty array when none).
data[].superseded_byobject | null{ id, links.self } of the survivor when this row was merged into another concept; otherwise null.
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.

Frequently asked questions

How do I search for fields by name?+
Pass the search query parameter with a partial name string. The search matches against both canonical_name and display_name using case-insensitive partial matching (ILIKE). For example, ?search=invoice matches fields named invoice_number, invoice_date, etc.
What determines a field's maturity level?+
Maturity levels are assigned automatically based on extraction frequency and consistency. Core fields (tier 1) appear frequently across multiple document types. Proven fields (tier 2) appear regularly but in fewer contexts. Candidate fields (tier 3) have been seen only a few times and may be promoted as more documents are processed.
Why did some fields disappear from GET /v1/fields?+
The list hides provisional rows (admission_state defaults to canonical) and rows merged into another concept (include_superseded defaults to false). Pass admission_state=all and include_superseded=true to see them. A stored id still resolves through GET /v1/fields/{id}, which reports superseded_by for merged rows.
What is the master_instruction field?+
The master_instruction is a synthesized extraction instruction automatically generated from the field's occurrence history. It describes how and where to find the field value in documents, and is used internally by the extraction pipeline to guide LLM extraction for that canonical field.