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.
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./v1/fieldsQuery parameters
core, proven, or candidate. Takes precedence over tier; an unknown value is a 400 invalid_maturity.maturity.canonical (admitted fields), provisional (the not-yet-admitted pool), or all (no filter). Other values fall back to canonical. Default: canonicalsuperseded_by). Default: false20descResponse
Response fields
core, proven, or candidate.canonical or provisional.{ id, links.self } of the survivor when this row was merged into another concept; otherwise null.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
Frequently asked questions
How do I search for fields by name?+
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?+
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?+
What is the master_instruction field?+
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.