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.
Engine-created matches that score 90 or above from EXACT and TOLERANCE rules are auto-confirmed immediately. Manual matches, created with POST /v1/matching/manual, 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 or revoking a CONFIRMED group returns its transactions to the unmatched pool. The status change and the transaction return happen atomically.
When Matcher changes the status of a match’s transactions, it changes all of them or none. A manual match that loses a race on a transaction gets 409, and Matcher applies nothing.

FUZZY and DATE_LAG matches are never auto-confirmed. Auto-confirmation at score ≥ 90 applies to 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 when it scores 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	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.

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 in the context and returns only 1:1 candidates from the opposite side. 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`	An un-match took back the confirmed match that created the obligation.

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

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

Three-character currency code.

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. To read the adjustments recorded against a context, use GET /v1/matching/contexts/{contextId}/adjustments. It accepts an optional matchGroupId filter, and pages with cursor.

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.

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:

Match status changes: A CONFIRMED group becomes REVOKED. A still-PROPOSED group becomes REJECTED.
Transactions returned: All associated transactions revert to UNMATCHED status atomically with the status change.
Confirmed effects withdrawn: For a CONFIRMED group, Matcher also withdraws its open-item residuals, voids its fee variances, and withdraws the exceptions it raised. These changes and the status change happen in one transaction.
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. 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. 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

Console

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