Reference Primitives

Reference primitives (reference data) are versioned lookup tables shared across your Talonic workspace. Upload key-value reference data once and reuse it across multiple schemas for consistent code mapping and value resolution.

Manage reference data from the Reference Data tab on the Documents page; the manager lives at /sources/reference-data. Datasets can be uploaded as CSV or XLSX files, or created from JSON rows via POST /v1/reference-data. Each reference dataset is versioned independently, and schemas reference a specific version to ensure stable resolution.

The lookup convention follows a key / value structure where the key is the output code and the value is the human-readable label. During extraction, the platform maps FROM labels found in documents TO the canonical codes defined in the reference dataset. This ensures consistent, machine-readable output regardless of how values appear in source documents.

Because reference data now sits on its own tab beside the document list, the tables your documents are checked against live next to the documents themselves. A typical setup step is to open Documents, switch to Reference Data, upload a CSV or XLSX of the codes your downstream system accepts, and then bind that dataset to the matching schema fields in the Spec composer. Keeping the code list in one versioned dataset means every Spec that binds it maps labels to the same codes, and an update is a new version you adopt deliberately rather than a silent change.

For best results, keep reference datasets focused on a single domain: for example, one dataset for country codes, another for currency codes, and another for product categories. This makes each dataset reusable across multiple schemas and simplifies maintenance. When updating a dataset, test the new version against a few sample documents before updating the version reference in production schemas.

# Create a reference dataset from JSON rows (requires write scope).
# Each row is an object; "columns" optionally fixes the column order.
curl -X POST https://api.talonic.com/v1/reference-data \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Country Codes",
    "columns": ["code", "label"],
    "data": [
      { "code": "US", "label": "United States" },
      { "code": "US", "label": "USA" },
      { "code": "DE", "label": "Germany" },
      { "code": "DE", "label": "Deutschland" },
      { "code": "GB", "label": "United Kingdom" },
      { "code": "GB", "label": "UK" }
    ]
  }'

# List reference datasets:
curl -s https://api.talonic.com/v1/reference-data \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Browse rows in a dataset (paginated with page/limit, limit capped at 500):
curl -s "https://api.talonic.com/v1/reference-data/rd_001/rows?page=1&limit=100" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Reference data is the centralized source of truth for code mapping across your workspace. Unlike schema-level reference tables that are defined inline and scoped to a single schema, workspace-level reference datasets are shared resources that any schema can reference. This eliminates duplication: instead of maintaining identical country code tables across five schemas, you maintain one dataset and reference it from all five. When a new country or code variation needs to be added, you update the dataset once and bump the version reference in each schema. The three-stage lookup cascade (normalization, fuzzy, AI fallback) runs identically for both shared reference data and inline tables, so there is no difference in resolution quality.

• Key-value structure — key is the canonical code, value is the label the platform matches against.
• Independent versioning — each update creates a new version; schemas pin to a specific version.
• Cross-schema sharing — one reference dataset can be referenced by any number of schemas.
• Three-stage lookup cascade — string normalization, token fuzzy matching, and Haiku LLM fallback for ambiguous values.