Get Field & Similar Fields
Retrieve a canonical field by ID with its 20 most recent occurrences, or find semantically similar fields ranked by embedding cosine similarity, top 10.
The GET /v1/fields/:id endpoint retrieves the full details of a canonical field from the Field Registry, including its metadata and the 20 most recent extraction occurrences (recent_occurrences). Each occurrence shows which document the field was extracted from, the raw field name as it appeared in that document, the extracted value, and when the extraction happened.
Occurrences give you a window into how a field is actually used across your document corpus. They reveal naming variations (e.g. a field canonicalized as invoice_number might appear as Inv. No., Invoice #, or Rechnungsnummer in different documents), value distributions, and extraction recency.
The companion GET /v1/fields/:id/similar endpoint uses embedding cosine similarity to find up to 10 of the most semantically related fields in your registry. Each match includes a similarity score between 0 and 1, where 1.0 is an exact semantic match. This is useful for discovering near-duplicate fields that could be merged, or for finding related fields when building new schemas.
Pair these endpoints together for field audit workflows: fetch a field to understand its current usage, then check similar fields to identify potential duplicates or related concepts that should be grouped in the same schema.
/v1/fields/:idGet a field with recent occurrences
curl -H "Authorization: Bearer $TALONIC_API_KEY" \
"https://api.talonic.com/v1/fields/f1a2b3c4-d5e6-7890-abcd-ef1234567890"Get Field Response
Response fields
GET /v1/fields/:id Response
{
"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.",
"recent_occurrences": [
{
"id": "0c11ee22-aa33-bb44-cc55-dd6677889900",
"document_id": "aa11bb22-cc33-dd44-ee55-ff6677889900",
"document_filename": "invoice_2024_march.pdf",
"raw_field_name": "Invoice No.",
"value": "INV-2024-00847",
"created_at": "2024-12-01T08:30:00.000Z"
},
{
"id": "1d22ff33-bb44-cc55-dd66-ee7788990011",
"document_id": "bb22cc33-dd44-ee55-ff66-778899001122",
"document_filename": "rechnung_q4.pdf",
"raw_field_name": "Rechnungsnummer",
"value": "RE-2024-12345",
"created_at": "2024-11-28T14:15:00.000Z"
},
{
"id": "2e33aa44-cc55-dd66-ee77-ff8899001122",
"document_id": "cc33dd44-ee55-ff66-7788-990011223344",
"document_filename": "facture_nov.pdf",
"raw_field_name": "N° de facture",
"value": "FAC-2024-0091",
"created_at": "2024-11-25T11:00:00.000Z"
}
],
"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"
}
}Similar Fields
Find the 10 most semantically similar fields to a given field using embedding cosine similarity. Each result includes a similarity score from 0 to 1, where higher values indicate closer semantic meaning. Fields with scores above 0.85 are strong candidates for merging.
/v1/fields/:id/similarSimilar Fields Response
Response fields
GET /v1/fields/:id/similar Response
{
"data": [
{
"id": "d4e5f6a7-b8c9-0123-def0-678901234567",
"canonical_name": "invoice_no",
"similarity": 0.94,
"links": {
"self": "/v1/fields/d4e5f6a7-b8c9-0123-def0-678901234567"
}
},
{
"id": "e5f6a7b8-c9d0-1234-ef01-789012345678",
"canonical_name": "reference_number",
"similarity": 0.78,
"links": {
"self": "/v1/fields/e5f6a7b8-c9d0-1234-ef01-789012345678"
}
},
{
"id": "f6a7b8c9-d0e1-2345-f012-890123456789",
"canonical_name": "po_number",
"similarity": 0.72,
"links": {
"self": "/v1/fields/f6a7b8c9-d0e1-2345-f012-890123456789"
}
}
]
}data array with a message explaining why. Embeddings are computed as the registry processes fields, so retry later or check another field. Fetch each match by its links.self URL to compare data types and maturity levels before merging.Errors
Error responses
Frequently asked questions
Why does the field detail only show 20 occurrences?+
recent_occurrences array returns the 20 most recent occurrences to keep response sizes manageable. For fields with thousands of occurrences, the full history is available through the platform UI. The occurrence_count field shows the total count across all documents.What does the similarity score mean?+
Can I use the similar fields endpoint to find merge candidates?+
links.self URL and review the occurrences and data types of both fields to confirm they represent the same concept before merging in the platform UI. Fields with high name similarity but different data types may be distinct concepts with similar names.What is the raw_field_name in occurrences?+
raw_field_name is the original field name as it appeared in the source document before canonicalization. For example, a field canonicalized as invoice_number might have raw names like Inv. No., Invoice #, or Rechnungsnummer depending on the document. This helps you understand the naming variations the registry has normalized.