Matching Configurations

A matching configuration defines how extracted document data is compared against a reference dataset. It specifies which extracted fields map to which reference columns, which matching strategy (exact, fuzzy, date_range, or numeric_range) each pair uses, and the relative weight that determines how much each comparison contributes to the overall confidence score. An auto-accept threshold (default 0.85) controls which matches are accepted without review.

Spec-rail Matching vs. this workflow

A Spec rail can include a Matching stage that links each document to a reference row as a pipeline phase. That stage is decisive-only: every document ends in exactly one of three terminal verdicts — auto_match (one candidate wins by a clear margin), shortlist (up to a handful of rivals the evidence cannot separate, surfaced side by side), or no_match. The Spec-rail matcher never routes anything to review: there are no matcher holds, and a shortlist is display-only evidence, never a queue item.

The stage's decision policy lives under decision in the matcher config. decision.min_score and decision.auto_match_margin are required, and both sit on a signed log-weight scale — a unique-identifier column match alone scores roughly 6-8 and 0 is neutral, so this is not a 0-1 probability. decision.shortlist_max caps how many rivals a shortlist can carry (an integer from 2 to 5, default 3); when more rivals clear the gates than the cap allows, the verdict is no_match with reason too_many_rivals. The legacy keys decision.mode and decision.review_mode are still accepted so old Spec JSONs keep validating, but both are ignored — no configuration can re-enable review holds.

When the stage runs with batch context (batch_context.enabled: true), matched documents in a batch help their neighbors: batch inheritance (batch_context.inherit_to_unmatched) defaults on, letting an unmatched document inherit the linkage its batch agrees on, and is opted out per stage by setting the key to false. The legacy engine documented on the rest of this page behaves differently: it keeps a three-way review band, classifying each result as matched, review, or no_match against the configuration threshold. Legacy runs are standalone — they never hold a pipeline.

Matching strategies

• exact — case-insensitive string comparison. Best for unique identifiers like PO numbers, invoice IDs, and reference codes where values should match verbatim.
• fuzzy — token-based similarity with a configurable threshold. Handles misspellings, abbreviations, and word reordering. Ideal for company names, addresses, and descriptions.
• date_range — matches dates within a configurable tolerance window (e.g., +/- 7 days). Useful when documents report dates with slight offsets, such as invoice date vs. received date.
• numeric_range — matches numbers within a percentage or absolute tolerance. Handles rounding differences in amounts, quantities, and prices across systems.

Weights and setup workflow

Each field comparison carries a weight that determines how much it contributes to the overall confidence score. Set high weights on fields that are strong identifiers (like reference numbers or unique IDs) and lower weights on fields that are common or prone to variation (like names or descriptions). Weights are relative: the weighted aggregate produces a final confidence score between 0 and 1, displayed as a percentage in the app.

Each mapping can also carry per-field tuning. A fuzzy_string mapping accepts its own threshold (the similarity a token comparison must reach, defaulting to 0.8), a date_range mapping takes tolerance_days, and a numeric_range mapping takes tolerance_pct for a percentage tolerance. A mapping with "mode": "extract_only" is excluded from scoring entirely — useful for carrying a reference column (say, an internal account code) in the mapping without letting it sway the confidence.

You can also use AI strategy generation to let the platform suggest a matching strategy automatically. It analyzes the reference data shape and your target scope (a run, a schema, or a document filter), then synthesizes a draft strategy with field rules, blocking keys, and thresholds that you review and adjust before executing. Most teams start with AI strategy generation and fine-tune based on initial results: a common pattern is a high-weight exact match on a unique identifier (like a PO number) combined with lower-weighted fuzzy matches on name and description fields as supporting evidence.

curl -X POST https://api.talonic.com/v1/matching/configs \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice to PO Matching",
    "reference_data_id": "b8c9d0e1-…",
    "threshold": 0.85,
    "field_mappings": [
      { "extracted_field": "vendor_name", "reference_field": "vendor_name", "match_type": "fuzzy_string", "weight": 0.4 },
      { "extracted_field": "po_number", "reference_field": "po_number", "match_type": "exact", "weight": 0.35 },
      { "extracted_field": "total_amount", "reference_field": "amount", "match_type": "numeric_range", "weight": 0.15, "tolerance_pct": 1 },
      { "extracted_field": "invoice_date", "reference_field": "po_date", "match_type": "date_range", "weight": 0.1, "tolerance_days": 7 }
    ]
  }'

# threshold = auto-accept confidence threshold (defaults to 0.85).
# match_type values on the wire: exact | fuzzy_string | date_range | numeric_range.

curl -X POST https://api.talonic.com/v1/matching/strategies/generate \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_data_id": "b8c9d0e1-…",
    "target_type": "run",
    "target_value": { "run_id": "d4e5f6a7-…" },
    "user_prompt": "Match invoices to the vendor registry; PO number is authoritative."
  }'

# Response (201): the generated strategy entity, including field_rules,
# blocking_keys, thresholds, and a reasoning_summary. Review it (or PATCH
# /v1/matching/strategies/{id} to adjust), then execute it with
# POST /v1/matching/configs/{id}/smart-run.