Skip to main content

Match Results

Match results are presented per document, with the top 5 candidates ranked by weighted confidence score. Each candidate includes a confidence score and field-level evidence showing which comparisons contributed to the match: the strategy used for each field (exact, fuzzy, date_range, or numeric_range), the individual field score, and the actual values that were compared on both sides. This transparency makes it straightforward to verify correct matches and investigate false positives.

Each result also carries a per-result status: matches scoring at or above the configuration's auto-accept threshold are marked auto_accepted, borderline results are marked needs_review, and documents with no viable candidate are marked no_match. The API reports confidence as a fraction between 0 and 1; the app displays it as a percentage.

Reviewing and approving matches

When reviewing results, focus on documents where the top candidate has a confidence score between roughly 50% and 85%: these are the borderline cases that benefit most from human judgment. High-confidence matches (above the auto-accept threshold) are usually correct, while very low scores typically indicate no valid match exists in the reference data.

Approved matches flow downstream into delivery pipelines, where they can be included in structured exports alongside extraction data. Rejected matches are excluded from future consideration for that document, which helps the system learn from your decisions when running subsequent matching passes.

Result fields

ParameterTypeDescription
ConfidencescoreWeighted aggregate score across all field comparisons (0-1 in the API, shown as a percentage in the app).
EvidencedetailPer-field breakdown showing strategy used, individual score, and matched values.
StatusstatePer-result state: auto_accepted, needs_review, or no_match.
Top 5candidatesThe five highest-scoring reference records for each document.
You can approve or reject individual match results. Approved matches can be used downstream in delivery pipelines. Rejected matches are excluded from future consideration for that document.
Get match results for a completed run
curl -s https://api.talonic.com/v1/matching/runs/RUN_UUID/results \
  -H "Authorization: Bearer $TALONIC_API_KEY"

# Response:
# {
#   "data": [
#     {
#       "id": "e7f8a9b0-…",
#       "document_id": "f0e1d2c3-…",
#       "document_filename": "Invoice_ACME.pdf",
#       "matched_reference_row_id": "a1b2c3d4-…",
#       "confidence": 0.87,
#       "status": "needs_review",
#       "evidence": {
#         "candidates": [
#           {
#             "fields": [
#               { "field": "vendor_name", "strategy": "fuzzy", "score": 0.92,
#                 "source_value": "Acme Corp", "target_value": "ACME Corporation" },
#               { "field": "total_amount", "strategy": "numeric_range", "score": 1.0,
#                 "source_value": "12450.00", "target_value": "12450.00" }
#             ]
#           }
#         ]
#       }
#     }
#   ]
# }
Approve or reject a match result
curl -X POST "https://api.talonic.com/v1/matching/runs/RUN_UUID/results/RESULT_UUID/review" \
  -H "Authorization: Bearer $TALONIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved", "notes": "Verified against Q1 vendor statement." }'

# status: "approved" or "rejected"; notes are optional.

Consider a practical example: you receive an invoice from "Acme Corp" with a total of $12,450 dated 2025-03-15. The matching engine returns the top candidate as "ACME Corporation" in your reference data with 87% confidence. The evidence view shows the vendor name scored 92% via fuzzy match (handling "Corp" vs "Corporation"), the amount scored 100% via numeric_range, and the date scored 78% via date_range because the reference shows a PO date of 2025-03-10, within the 7-day tolerance. You can quickly verify the match is correct and approve it, sending the linked record downstream.

Frequently asked questions

How are match results presented?+
Results show the top 5 candidates per document, each with a weighted confidence score and per-field evidence showing the strategy, individual score, and the values compared. The API reports confidence as a 0-1 fraction; the app displays percentages.
What evidence is provided for each match?+
Per-field evidence shows the strategy used (exact, fuzzy, date_range, numeric_range), the individual score, and the matched values for both the extracted data and the reference record.
Can I approve or reject match results?+
Yes. Each match result can be individually approved or rejected via POST /v1/matching/runs/{runId}/results/{resultId}/review with a status of "approved" or "rejected" and optional notes. Approved matches flow to downstream delivery pipelines; rejected matches are excluded from future consideration for that document.
Why does a match have a low confidence score?+
Low confidence usually means the fields being compared have significant differences or the matching strategies produced weak scores. Check the per-field evidence to identify which comparisons dragged the score down, then consider adjusting weights or strategies in the matching configuration.
Do approved match results feed into delivery pipelines?+
Yes. Approved matches can be included in structured exports and delivery payloads alongside extraction data. This enables end-to-end workflows where extracted document data is matched against reference records and the combined result is delivered to your downstream system in a single payload.

Related

Matching Configurations
Running Matches
Reference Data