> ## 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
> Understand the five core concepts that power Matcher: contexts, sources, field maps, rules, and matches.
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.
A context answers: *what am I matching against what?*
### 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
* **Bank**: Statements or feeds from banks
* **ERP**: SAP, Oracle, NetSuite exports
* **Ledger**: Internal ledger systems (including Midaz)
* **Payment processor**: Stripe, Adyen, PayPal settlements
* **Card network**: Visa, Mastercard, Elo files
### Source setup
Each source has:
* **Name**: Label it (e.g., "Chase Checking")
* **Type**: Category (bank, ERP, etc.)
* **Field map**: How its fields map to Matcher's 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 | Type | Description |
| ---------------- | -------- | ----------------------------------------- |
| `transaction_id` | String | Source-system transaction identifier |
| `amount` | Decimal | Transaction amount (positive or negative) |
| `currency` | String | ISO 4217 currency code |
| `date` | DateTime | Transaction date |
| `reference` | String | External reference or description |
| `metadata` | Object | Source-specific attributes |
### Example mapping
A bank statement exposing `TXN_ID`, `VALUE`, `CCY`, and `POST_DATE` would be mapped as:
```json theme={null}
{
"transaction_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)
### 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 | `fields`: list of fields to compare |
| TOLERANCE | `percent`: percentage variance, `absolute`: fixed variance amount |
| DATE\_LAG | `days_before`, `days_after`: allowed offset from transaction date |
## 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 |
### 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 |
| `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 |
| Rule match | 10% | Deterministic rule application |
### Confidence tiers
| Tier | Score range | System behavior |
| ----------------- | ----------- | ------------------------- |
| **Auto-approved** | ≥ 90 | Confirmed automatically |
| **Needs review** | 60–89 | Flagged for manual review |
| **No match** | \< 60 | Treated as an exception |
Confidence thresholds can be customized per tenant to reflect different risk tolerances.
## 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 |
| --------------- | ----------------------------------- |
| `timestamp` | Action timestamp (UTC) |
| `user_id` | Actor responsible for the action |
| `action` | Action performed |
| `resource_type` | Affected resource type |
| `resource_id` | Identifier of the affected resource |
| `before_state` | State before the action |
| `after_state` | State after the action |
| `notes` | Justification, when applicable |
Audit logs are append-only. Entries cannot be modified or removed.
## Next steps
***
See how these concepts are implemented across bounded contexts.
Apply these concepts in a guided, hands-on flow.