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 reject proposed or revoke confirmed match groups.

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.
Eligible engine-created matches (score 90 or above) from EXACT and TOLERANCE rules are auto-confirmed immediately. Manual matches start in CONFIRMED status. FUZZY and DATE_LAG matches remain PROPOSED and are never auto-confirmed.
Matches that are not auto-confirmed remain in PROPOSED. The public match-group API does not expose manual confirmation, but you can reject a proposed group with the unmatch operation and a required reason.
Rejecting a PROPOSED group returns its transactions to the unmatched pool. You can revoke a CONFIRMED group only when Matcher can also reverse every residual/open-item effect that confirmation applied. On success, those changes and the transaction return happen atomically.

FUZZY and DATE_LAG matches are never auto-confirmed. Auto-confirmation at score ≥ 90 applies to eligible engine-created EXACT and TOLERANCE matches. A manual match starts in CONFIRMED status. A match produced by a FUZZY or DATE_LAG rule stays in PROPOSED, regardless of its score, even a FUZZY match scoring 90+. You can reject it through the unmatch operation. There is no public manual-confirm operation. See Confidence scoring.

Match Status Lifecycle — Status lifecycle of a match.

Status definitions

Status	Description	Next Actions
`PROPOSED`	Match identified by the system but not confirmed	Review or reject through the unmatch operation
`CONFIRMED`	Match was auto-confirmed or created as a manual match	Revoke through the unmatch operation 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 what happens to the match.

Confidence levels

Tier	Score range	Behavior
Auto-confirm eligible	90-100	Eligible engine-created EXACT and TOLERANCE matches are automatically confirmed without manual review. Manual matches are created `CONFIRMED`; FUZZY and DATE_LAG matches remain `PROPOSED`.
Needs Review	60-89	Medium confidence matches remain `PROPOSED`. You can review and reject them, but the public API does not expose manual confirmation.
No Match	Below 60	Low confidence candidates are not proposed as matches and become exceptions.

Understanding the score

Matcher calculates the confidence score 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

Matcher gives you three surfaces for working a review queue: 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. The limit defaults to 50 and accepts values from 1 to 200. The candidate picker scans at most 5,000 unmatched transactions from the opposite side and returns only 1:1 candidates. It applies the shared scorer to raw transaction data, without the run-time fee normalization or FX variance-band matching used by a matching run.

List open items

Open items are residual balances that remain when a transaction nets only in part. 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 remained open beyond its aging threshold, measured from the obligation business date or the legacy first-seen time.
`WITHDRAWN`	A confirmed-group unmatch removed the final live contribution behind the obligation. The item remains as history, but is terminal and cannot be netted or carried forward.

The normal lifecycle flows OPEN → PARTIALLY_CLEARED → CLEARED, with any still-open item able to become AGED once it passes the aging threshold. A successful confirmed-group unmatch withdraws that group’s residual effects. If no live contribution remains behind the obligation, the item ends WITHDRAWN. That status means the unmatch took the item back. It does not mean the item cleared or aged.

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:

String

required

Adjustment amount

String

required

Non-empty currency string. Matcher does not validate ISO 4217 membership for this adjustment.

String

required

DEBIT or CREDIT

String

required

BANK_FEE, FX_DIFFERENCE, ROUNDING, WRITE_OFF, or MISCELLANEOUS

String

required

Business reason for the adjustment

String

required

Human-readable description

UUID

Match group the adjustment applies to

UUID

Transaction the adjustment applies to

Send at least one of matchGroupId or transactionId.

API Reference:

Rejecting or revoking match groups

Use the unmatch operation to reject a PROPOSED group or revoke a CONFIRMED group. After a successful operation, Matcher returns the group’s transactions to UNMATCHED. The next run can match them 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 mandatory and must not be empty. For a CONFIRMED group, Matcher verifies the residual/open-item reversal before it changes the group or its transactions. A successful operation atomically appends the compensating ledger entries, revokes the group, and returns its transactions to UNMATCHED.

The unmatch operation requires a non-empty reason. For a confirmed group, it either reverses the residual/open-item effects together with the group and its transactions, or returns 409 Conflict before changing anything. A later live entry on the residual blocks the earlier reversal. A newer live obligation on the same identity also blocks it when restoring a terminal item would conflict.

When to reject or revoke

Common scenarios for rejecting or revoking a group:

Incorrect match confirmed: the transactions in a confirmed group 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 is a duplicate that you should remove

What happens after unmatch

When you unmatch a match group:

Confirmed residuals come first: Matcher verifies that it can reverse every residual/open-item effect of a CONFIRMED group. If a later entry or a conflicting newer obligation blocks it, the operation returns 409 Conflict and leaves the group, transactions, and open items unchanged.
Match status changes: A CONFIRMED group becomes REVOKED. A still-PROPOSED group becomes REJECTED.
Transactions returned: On success, all associated transactions revert to UNMATCHED status.
Open-item effects reversed: On a confirmed-group unmatch, compensating ledger entries take back the group’s residual effects in the same transaction. If that leaves no live contribution behind an obligation, it becomes terminal WITHDRAWN and does not carry forward.
Reason recorded: The group stores the supplied rejection or revocation reason.
Streaming event emitted: A match_group.unmatched event is emitted only when the group was previously CONFIRMED.
Re-matching possible: after a successful unmatch, the next run can match the transactions again.

Best practices

Start with lowest confidence matches

Review matches with the lowest confidence scores first. These matches are the most likely to be wrong. Give them the most attention.

Understand fixed confidence thresholds

The confidence thresholds do not change. Eligible engine-created EXACT and TOLERANCE matches with scores of 90 or above are auto-confirmed. Manual matches start CONFIRMED. Scores between 60 and 89 remain PROPOSED, and 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 remain PROPOSED, regardless of score.Use rule tuning (priority, tolerance values) to influence how many matches land in each tier.

Give a clear reason

Provide a specific reason when rejecting a proposed group or revoking a confirmed group. The unmatch operation requires it and stores it with the group.

Reject only after checking the source data

Review the group and its source transactions before using the unmatch operation. Matcher exposes this operation per group. It does not expose bulk confirmation.

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

Rejecting or revoking match groups

When to reject or revoke

What happens after unmatch

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

​Rejecting or revoking match groups

​When to reject or revoke

​What happens after unmatch

​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

Rejecting or revoking match groups

When to reject or revoke

What happens after unmatch

Best practices

Next steps