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

# Matcher concepts

> Learn Matcher's five core concepts — contexts, sources, field maps, match rules, and matches — that shape every reconciliation you build.

The five core concepts in Matcher: **contexts**, **sources**, **field maps**, **rules**, and **matches**. Understand these and you'll understand how the entire system works.

## Context

***

A **context** defines what you're reconciling. It's the container that holds your sources, rules, and results.

<Info>
  A context answers: *what am I matching against what?*
</Info>

### Context types

| Type    | Description                 | Example                                |
| ------- | --------------------------- | -------------------------------------- |
| **1:1** | One-to-one reconciliation   | Bank statement vs ERP records          |
| **1:N** | One-to-many reconciliation  | One payment covering multiple invoices |
| **N:M** | Many-to-many reconciliation | Netting or aggregation scenarios       |

### Example

A context named **"Chase Bank vs ERP System"** would:

* Define Chase Bank as one reconciliation source
* Define your ERP system as another source
* Specify the rules used to reconcile transactions between them

## Source

***

A **source** is where transactions come from. Every context needs at least two sources—that's what you're reconciling.

### Source types

* **LEDGER**: Internal ledger systems (including Midaz)
* **BANK**: Bank statement feeds
* **GATEWAY**: Payment gateway settlements (Stripe, Adyen, PayPal)
* **CUSTOM**: Bespoke, user-defined feeds
* **FETCHER**: Sources pulled automatically by the discovery engine (aggregator connections)

### Source setup

Each source requires:

* **Name**: Label it (e.g., "Chase Checking")
* **Type**: Category (`LEDGER`, `BANK`, `GATEWAY`, `CUSTOM`, or `FETCHER`)
* **Side**: Which matching side it feeds (`LEFT` or `RIGHT`)
* **Config**: Source-specific connection and parsing settings

Field maps translate each source's fields into Matcher's standard schema.

## Field map

***

A **field map** translates external field names into Matcher's standard schema. Every system calls things differently—field maps normalize that.

### Standard fields

| Field          | Required | Type     | Description                               |
| -------------- | -------- | -------- | ----------------------------------------- |
| `external_id`  | Yes      | String   | Source-system transaction identifier      |
| `amount`       | Yes      | Decimal  | Transaction amount (positive or negative) |
| `currency`     | Yes      | String   | ISO 4217 currency code                    |
| `date`         | Yes      | DateTime | Transaction date                          |
| `description`  | No       | String   | External reference or description         |
| `fee_amount`   | No       | Decimal  | Optional fee amount column                |
| `fee_currency` | No       | String   | Optional fee currency column              |

The canonical vocabulary is closed — a field map that declares any other key is rejected.

### Example mapping

A bank statement exposing `TXN_ID`, `VALUE`, `CCY`, and `POST_DATE` would be mapped as:

```json theme={null}
{
  "external_id": "TXN_ID",
  "amount": "VALUE",
  "currency": "CCY",
  "date": "POST_DATE"
}
```

## Match rule

***

A **match rule** tells Matcher how to compare transactions. Rules run in priority order—first match wins.

### Rule types

* **EXACT**: Fields must match exactly (amount, date, reference)
* **TOLERANCE**: Allow small differences (0.5% variance, \$10 absolute)
* **DATE\_LAG**: Match within a date window (±3 days). Like FUZZY, DATE\_LAG matches never auto-confirm — they always go to manual review.
* **FUZZY**: Graded similarity on references/descriptions (normalized, substring, or similarity-scored). FUZZY only proposes—it never auto-confirms, so a human reviews every fuzzy link.

### Priority order

Lower numbers run first. Matcher stops at the first matching rule.

| Priority | Rule               | Description                            |
| -------- | ------------------ | -------------------------------------- |
| 1        | Exact match        | Amount, date, and reference must match |
| 2        | Same-day tolerance | Same date, amount within 0.5%          |
| 3        | Week tolerance     | Within 7 days, amount within 1%        |

### Rule parameters

| Rule type | Parameters                                                                                     |
| --------- | ---------------------------------------------------------------------------------------------- |
| EXACT     | `matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: which fields must match exactly |
| TOLERANCE | `tolerance`: object with `percentTolerance` and/or `absTolerance` (decimal strings)            |
| DATE\_LAG | `minDays`, `maxDays`: allowed day-difference band, plus `inclusive` for the upper bound        |

## Match

***

A **match** is when transactions from different sources are reconciled together. It's the end goal.

### Match status

| Status      | Description                                                                      |
| ----------- | -------------------------------------------------------------------------------- |
| `PROPOSED`  | Matcher found it, waiting for confirmation                                       |
| `CONFIRMED` | Auto-approved or manually approved                                               |
| `REJECTED`  | Manually rejected                                                                |
| `REVOKED`   | A previously confirmed match was unmatched, returning its transactions to review |

### Match patterns

#### 1:1 match

One transaction from each source is reconciled.

```
Bank: $100.00 on Jan 15 → ERP: $100.00 on Jan 15
```

#### 1:N match

One transaction is reconciled against multiple transactions.

```
Bank: $300.00 → ERP: $100.00 + $100.00 + $100.00
```

#### N:1 match

Multiple transactions are reconciled against a single transaction.

```
Bank: $50.00 + $50.00 + $50.00 → ERP: $150.00

```

### Match items

Each match group contains **match items**, which record transaction participation and allocation.
This enables partial reconciliation in split and aggregation scenarios.

## Exception

***

An **exception** is a transaction that didn't match. It needs manual review.

### Exception status

| Status               | Description                                      |
| -------------------- | ------------------------------------------------ |
| `OPEN`               | Waiting for assignment                           |
| `ASSIGNED`           | Someone's investigating                          |
| `PENDING_RESOLUTION` | A resolution is in progress, awaiting completion |
| `RESOLVED`           | Handled                                          |

### Severity

Matcher auto-classifies exceptions so you know what to prioritize.

| Severity     | Default criteria                                     |
| ------------ | ---------------------------------------------------- |
| **Critical** | Amount ≥ \$100K, age ≥ 5 days, or regulatory flagged |
| **High**     | Amount ≥ \$10K or age ≥ 3 days                       |
| **Medium**   | Amount ≥ 1,000 or age ≥ 1 day                        |
| **Low**      | All other cases                                      |

### Resolution types

* **Force match**: Manually reconcile transactions
* **Adjustment**: Record a compensating adjustment
* **Write-off**: Close the exception with justification

## Confidence score

***

A **confidence score** indicates the reliability of an automated match on a 0–100 scale.
Higher scores represent stronger alignment between transactions.

### Score calculation

| Component             | Weight | Description                                                  |
| --------------------- | ------ | ------------------------------------------------------------ |
| Amount match          | 40%    | Degree of amount alignment                                   |
| Currency match        | 30%    | Currency consistency                                         |
| Date tolerance        | 20%    | Proximity of transaction dates                               |
| Reference/description | 10%    | Reference/description alignment (graded 0–1 for FUZZY rules) |

### Confidence tiers

| Tier              | Score range | System behavior                                                                                    |
| ----------------- | ----------- | -------------------------------------------------------------------------------------------------- |
| **Auto-approved** | ≥ 90        | Confirmed automatically (EXACT and TOLERANCE rules only — FUZZY and DATE\_LAG always go to review) |
| **Needs review**  | 60–89       | Flagged for manual review                                                                          |
| **No match**      | \< 60       | Treated as an exception                                                                            |

<Note>
  Confidence weights and tier thresholds are fixed by the engine and are not configurable.
</Note>

## Audit log

***

An **audit log** is an immutable record of all system actions.
It provides full traceability for operational review, audits, and regulatory compliance.

### Logged events

Audit entries are created for:

* Context, source, and rule changes
* File ingestion and processing
* Match confirmations and rejections
* Exception resolution and overrides

### Audit entry contents

| Field                     | Description                                                                    |
| ------------------------- | ------------------------------------------------------------------------------ |
| `createdAt`               | Action timestamp (UTC)                                                         |
| `actorId`                 | Actor responsible for the action                                               |
| `action`                  | Action performed                                                               |
| `entityType`              | Affected entity type                                                           |
| `entityId`                | Identifier of the affected entity                                              |
| `changes`                 | What changed, as a structured diff                                             |
| `tenantSeq`               | Per-tenant sequence number                                                     |
| `prevHash` / `recordHash` | Hash chain linking each entry to the previous one, making tampering detectable |

<Warning>
  Audit logs are append-only. Entries cannot be modified or removed.
</Warning>

## Next steps

***

<Card title="Architecture" icon="sitemap" href="/en/matcher/matcher-architecture" horizontal>
  See how these concepts are implemented across bounded contexts.
</Card>

<Card title="Quick start" icon="rocket" href="/en/matcher/getting-started/matcher-quick-start" horizontal>
  Apply these concepts in a guided, hands-on flow.
</Card>