Reviewing matches

After running a matching job, you’ll need to review the results. This guide explains how to interpret match results, understand confidence scores, and approve or reject proposed matches.

Match status lifecycle

Matches progress through a defined lifecycle:

When the matching engine finds a pair of transactions that belong together, it creates a match in PROPOSED status.
High-confidence matches (score 90 or above) from EXACT and TOLERANCE rules, plus manual matches, are auto-confirmed immediately. FUZZY and DATE_LAG matches always require manual review and are never auto-confirmed.
Lower-confidence matches wait for manual review—an analyst can then confirm or reject them.
Rejected transactions return to the unmatched pool for another matching attempt.

FUZZY and DATE_LAG matches are never auto-confirmed. Auto-confirmation at score ≥ 90 applies to EXACT and TOLERANCE rules, plus manual matches. A match produced by a FUZZY or DATE_LAG rule always stays in PROPOSED for manual review, regardless of its score — even a FUZZY match scoring 90+. See Confidence scoring.

Match Status Lifecycle — Status lifecycle of a match.

Status definitions

Status	Description	Next Actions
`PROPOSED`	Match identified by the system, awaiting confirmation	Review, confirm, or reject
`CONFIRMED`	Match has been approved (auto or manual)	Revoke if incorrect
`REJECTED`	Match was declined	Transactions return to unmatched pool
`REVOKED`	A previously confirmed match was revoked	Transactions return to unmatched pool

Confidence tiers

Matcher assigns a confidence score (0-100) to each proposed match. The score determines how the match is handled.

Confidence levels

Tier	Score range	Behavior
Auto-Approved	90-100	High confidence matches are automatically confirmed without manual review (EXACT and TOLERANCE rules, plus manual matches; FUZZY and DATE_LAG matches always require review).
Needs Review	60-89	Medium confidence matches require manual review before confirmation.
No Match	Below 60	Low confidence candidates are not proposed as matches and become exceptions.

Understanding the score

The confidence score is calculated from weighted components:

Component	Weight	What it Measures
Amount match	40%	How closely transaction amounts align
Currency match	30%	Whether currencies are the same
Date tolerance	20%	How close the transaction dates are
Reference match	10%	Whether transaction references match

Example Score Breakdown:

Match: BANK-001 ↔ LED-001

Amount: $1,000.00 vs $1,000.00 → 100% × 40% = 40 points
Currency: USD vs USD → 100% × 30% = 30 points
Date: 2024-01-15 vs 2024-01-15 → 100% × 20% = 20 points
Reference: PAY-001 vs PAY-001 → match → 10 points
 ─────────────────────────
Total Confidence: 100 points

Understanding variances

When matches have differences, review the variance details:

Amount variance

Common causes of amount variance:

Bank fees
Currency conversion differences
Rounding differences
Partial payments

Date variance

Common causes of date variance:

Settlement timing
Time zone differences
Posting vs. transaction date
Weekend/holiday processing

Match candidates, open items, and adjustments

As you work a review queue, three questions come up again and again: why did the engine propose this pairing?, what’s still unsettled after a partial match?, and how do I book a small difference so both sides balance? Matcher answers each with a dedicated surface — match candidates, open items, and adjustments.

List match candidates

Retrieve the ranked candidate proposals the engine considered for a transaction — the “why” behind a proposed match, including the per-component contributions.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/candidates?contextId={contextId}&transactionId={transactionId}&limit=20" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/candidates accepts contextId, transactionId, and limit query parameters and returns a CandidateProposalsResponse.

List open items

Open items are residual balances left when a transaction is only partially netted. Track them to surface amounts that still need clearing or that have aged past their threshold.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/open-items?status=OPEN&limit=50" \
 -H "Authorization: Bearer $TOKEN"

GET /v1/matching/contexts/{contextId}/open-items supports a status filter, plus limit/cursor pagination.

Open item statuses

Status	When it occurs
`OPEN`	Fresh residual — the item has a remaining balance and no leg has netted against it yet.
`PARTIALLY_CLEARED`	At least one leg has netted against the balance, but a residual still remains.
`CLEARED`	The residual has been fully netted within tolerance.
`AGED`	The item exceeded its aging threshold while still open (unresolved past the configured SLA).

The lifecycle flows OPEN → PARTIALLY_CLEARED → CLEARED, with any still-open item able to become AGED once it passes the aging threshold.

Create an adjustment

Post an accounting adjustment to account for a variance (bank fee, FX difference, rounding, write-off, and so on) against a match group or transaction.

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/adjustments?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "amount": "10.50",
   "currency": "BRL",
   "direction": "DEBIT",
   "type": "BANK_FEE",
   "reason": "Variance due to bank processing fee",
   "description": "Bank wire fee adjustment",
   "matchGroupId": "019c96a0-0b74-768c-8d25-2bf065dca2f8"
 }'

POST /v1/matching/adjustments requires the contextId query parameter. Body fields:

amount

String

required

Adjustment amount

currency

String

required

ISO 4217 currency code

direction

String

required

DEBIT or CREDIT

type

String

required

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF, or MISCELLANEOUS

reason

String

required

Business reason for the adjustment

description

String

required

Human-readable description

matchGroupId

UUID

Match group the adjustment applies to

transactionId

UUID

Transaction the adjustment applies to

API Reference:

Revoking confirmed matches

Sometimes you need to reverse a match because it was approved incorrectly. The unmatch operation breaks an existing match group and returns its transactions to UNMATCHED status so they can be matched again. Use DELETE /v1/matching/groups/{matchGroupId} with the required contextId query parameter and a reason in the request body (operationId unmatch):

cURL

curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "incorrect match - amounts do not match"
 }'

A successful unmatch returns 204 No Content. The reason field is required (non-empty).

Unmatching a match group creates a full audit trail. This operation should be used carefully and only when necessary.

When to revoke

Common scenarios for revoking:

Incorrect match confirmed: The match was approved but transactions actually belong to different records
New information: Additional data shows the match is wrong
Source correction: The source system issued a correction or reversal
Duplicate transaction: One of the transactions was a duplicate that should be removed

What happens after revoke

When a match group is unmatched:

Match status changes: A CONFIRMED group becomes REVOKED; a still-PROPOSED group becomes REJECTED
Transactions returned: All associated transactions revert to UNMATCHED status
Audit trail created: Full record of who unmatched and the supplied reason
Webhook triggered: A match_group.unmatched event is emitted (only when the group was previously CONFIRMED)
Re-matching possible: Transactions can be matched again in the next run

Best practices

Start with lowest confidence matches

Review matches with the lowest confidence scores first. These are most likely to be incorrect and need the most attention.

Understand fixed confidence thresholds

Confidence thresholds are fixed in the system. For EXACT and TOLERANCE rules, plus manual matches, scores of 90 or above are auto-confirmed. Scores between 60 and 89 require manual review. Scores below 60 become exceptions. These values are not configurable per context. FUZZY and DATE_LAG matches are the exception: they are never auto-confirmed and always require review, regardless of score. Use rule tuning (priority, tolerance values) to influence how many matches land in each tier.

Document your decisions

Always add notes when confirming or rejecting matches. This creates an audit trail and helps team members understand the reasoning.

Use bulk operations wisely

Bulk confirm is efficient but use it only after reviewing a sample. Never bulk confirm without understanding what you’re approving.

Review high-value matches carefully

Regardless of confidence score, give extra attention to high-value matches. The impact of an incorrect match is proportional to the amount.

Overview

Guides

Matcher UI

MCP Server

Operations

Reviewing matches

Match status lifecycle

Status definitions

Confidence tiers

Confidence levels

Understanding the score

Understanding variances

Amount variance

Date variance

Match candidates, open items, and adjustments

List match candidates

List open items

Open item statuses

Create an adjustment

Revoking confirmed matches

When to revoke

What happens after revoke

Best practices

Next steps

Resolving exceptions

Confidence scoring

​Match status lifecycle

​Status definitions

​Confidence tiers

​Confidence levels

​Understanding the score

​Understanding variances

​Amount variance

​Date variance

​Match candidates, open items, and adjustments

​List match candidates

​List open items

​Open item statuses

​Create an adjustment

​Revoking confirmed matches

​When to revoke

​What happens after revoke

​Best practices

​Next steps

Resolving exceptions

Confidence scoring

Match status lifecycle

Status definitions

Confidence tiers

Confidence levels

Understanding the score

Understanding variances

Amount variance

Date variance

Match candidates, open items, and adjustments

List match candidates

List open items

Open item statuses

Create an adjustment

Revoking confirmed matches

When to revoke

What happens after revoke

Best practices

Next steps