> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Reviewing matches

> Review proposed matches after a run — understand the 0–100 confidence score, its four weighted components, variance causes, and how to confirm or reject.

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.

<Note>
  **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](/en/matcher/reference/matcher-confidence-scoring#fuzzy-matches-never-auto-confirm).
</Note>

<Frame caption="Status lifecycle of a match.">
  <img src="https://mintcdn.com/lerian-49cb71fc/SEOef3JqTInYAAau/images/en/d2/matcher-match-status.svg?fit=max&auto=format&n=SEOef3JqTInYAAau&q=85&s=e338f4d464ea2bd8f97e78ad28a6ed27" alt="Match Status Lifecycle" width="598" height="772" data-path="images/en/d2/matcher-match-status.svg" />
</Frame>

### 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.

```bash cURL theme={null}
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.

```bash cURL theme={null}
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.

```bash cURL theme={null}
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:

<ParamField path="amount" type="String" required>
  Adjustment amount
</ParamField>

<ParamField path="currency" type="String" required>
  ISO 4217 currency code
</ParamField>

<ParamField path="direction" type="String" required>
  `DEBIT` or `CREDIT`
</ParamField>

<ParamField path="type" type="String" required>
  `BANK_FEE`, `FX_DIFFERENCE`, `ROUNDING`, `WRITE_OFF`, or `MISCELLANEOUS`
</ParamField>

<ParamField path="reason" type="String" required>
  Business reason for the adjustment
</ParamField>

<ParamField path="description" type="String" required>
  Human-readable description
</ParamField>

<ParamField path="matchGroupId" type="UUID">
  Match group the adjustment applies to
</ParamField>

<ParamField path="transactionId" type="UUID">
  Transaction the adjustment applies to
</ParamField>

<Tip>
  API Reference:

  * [List match candidates](/en/reference/matcher/list-match-candidates)
  * [List open items](/en/reference/matcher/list-open-items)
  * [Create adjustment](/en/reference/matcher/create-adjustment)
</Tip>

## 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`):

```bash cURL theme={null}
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).

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

### 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:

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

## Best practices

***

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Document your decisions">
    Always add notes when confirming or rejecting matches. This creates an audit trail and helps team members understand the reasoning.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Next steps

***

<Card title="Resolving exceptions" icon="triangle-exclamation" href="/en/matcher/daily-reconciliation/matcher-resolving-exceptions" horizontal>
  Handle transactions that couldn't be matched automatically.
</Card>

<Card title="Confidence scoring" icon="chart-simple" href="/en/matcher/reference/matcher-confidence-scoring" horizontal>
  Deep dive into how confidence scores are calculated.
</Card>