> ## 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.
# Getting started with Matcher
> Walk through the five-stage reconciliation lifecycle, from defining a context to resolving exceptions on your first match run.
This guide walks through the reconciliation lifecycle in Matcher, from initial setup to reviewing results. It focuses on the concepts and decisions involved at each stage.
For step-by-step API instructions with request and response examples, see the [Matcher API quick start](/en/reference/matcher/matcher-developer-quick-start).
## The reconciliation lifecycle
***
Every reconciliation in Matcher follows the same five-stage lifecycle:
Create a context that describes what you are reconciling and how often.
Register the systems whose transactions you want to compare.
Configure the criteria Matcher uses to pair transactions.
Upload data and let Matcher find pairs, starting with a preview before committing.
Review unmatched transactions and decide how to handle them.
The sections below explain each stage.
## Define scope with a context
***
A **context** is the top-level container for a reconciliation workflow. It answers three questions:
* **What are you reconciling?** For example, a bank account against your general ledger.
* **What type of pairing?** One-to-one, one-to-many, or many-to-many.
* **How often?** Daily, weekly, monthly, or on demand.
| Pairing type | When to use | Example |
| ------------ | --------------------------------------------------- | ------------------------------------- |
| `1:1` | Each transaction has exactly one counterpart | Bank statement vs. ledger entries |
| `1:N` | One record maps to several on the other side | A single invoice paid in installments |
| `N:M` | Multiple records on both sides relate to each other | Batch payments split across accounts |
Most reconciliations start with `1:1`. You can change the pairing type later as your process evolves.
API reference: [Create context](/en/reference/matcher/create-context) | [Update context](/en/reference/matcher/update-context)
## Connect data sources
***
Each context needs at least **two sources**: the systems whose transaction data you want to compare. A source represents a single data feed such as a bank statement, a ledger export, or a payment gateway file.
### Source types
| Type | Typical use |
| --------- | -------------------------------------------- |
| `BANK` | Bank statements and account extracts |
| `LEDGER` | General ledger or ERP exports |
| `GATEWAY` | Payment processor data (Stripe, Adyen, etc.) |
| `CUSTOM` | Any other structured data |
### Field mapping
Transaction files from different systems rarely use the same column names. **Field maps** translate your source columns into Matcher's standard schema so transactions can be compared.
For example, a bank file might call the transaction date "Post Date", while your ledger calls it "posting\_date". Field maps normalize both to Matcher's `date` field.
Every transaction must provide at least four fields after mapping:
| Field | Description |
| ---------------- | --------------------------------------- |
| `transaction_id` | Unique identifier within the source |
| `amount` | Transaction value |
| `currency` | ISO 4217 currency code (e.g., USD, BRL) |
| `date` | Transaction date |
API reference: [Create source](/en/reference/matcher/create-source) | [Create field map](/en/reference/matcher/create-field-map)
## Set match rules
***
Rules define **how Matcher decides whether two transactions are the same**. You can stack multiple rules with different priorities. Matcher evaluates them in order: only transactions left unmatched by the first rule pass to the next.
### Rule types
| Rule | What it does | When to use |
| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------ |
| **Exact** | Requires identical values on the selected fields | When data is clean and systems are in sync |
| **Tolerance** | Allows small numeric or date differences | When bank fees, rounding, or processing delays cause minor discrepancies |
| **Date lag** | Permits a configurable date window | When settlement dates differ between systems |
### Recommended starting configuration
1. **Priority 1 — Exact rule** on amount, currency, and date. This catches all perfect matches first.
2. **Priority 10 — Tolerance rule** with a small amount tolerance (e.g., 1%) and a 2-day date window. This catches near-matches caused by fees or timing.
As you observe results over time, adjust rules or add new ones to improve your match rate.
API reference: [Create match rule](/en/reference/matcher/create-match-rule)
## Run matching
***
Once sources are configured and data is uploaded, you can run the matching engine.
### Preview first, commit second
Matcher supports two execution modes:
| Mode | Behavior |
| ----------- | --------------------------------------------------------------------------- |
| **Dry run** | Calculates matches and generates a preview. Nothing is persisted. |
| **Commit** | Persists the results: confirmed matches, confidence scores, and exceptions. |
Always start with a dry run. Review the preview to verify match quality before committing.
### Understanding confidence scores
Every match receives a confidence score from 0 to 100:
| Score range | Meaning | Action required |
| ----------- | ----------------- | ---------------------------------- |
| 90–100 | High confidence | Auto-confirmed, no action needed |
| 60–89 | Medium confidence | Flagged for manual review |
| Below 60 | Low confidence | Not matched — becomes an exception |
Scores are determined by how closely the transactions align across the matched fields and which rule produced the match. Exact rules yield higher scores than tolerance rules.
API reference: [Run match](/en/reference/matcher/run-match) | [List match run groups](/en/reference/matcher/list-match-run-groups)
## Resolve exceptions
***
Exceptions are transactions that Matcher could not pair automatically. They represent the items that need human attention.
### Exception severity
Matcher classifies each exception by severity based on the transaction amount and how long it has been unmatched:
| Severity | Criteria | Suggested SLA |
| ------------ | ------------------------------------------- | ------------- |
| **Critical** | Amount >= 100,000 or unmatched >= 120 hours | 24 hours |
| **High** | Amount >= 10,000 or unmatched >= 72 hours | 72 hours |
| **Medium** | Amount >= 1,000 or unmatched >= 24 hours | 5 days |
| **Low** | All others | 7 days |
### Resolution options
* **Force match** — Manually pair the transaction with a counterpart when you know they belong together.
* **Create adjustment** — Record a correcting entry to account for the difference.
* **Unmatch** — If a confirmed match is incorrect, undo it so both transactions return to the unmatched pool.
* **Dispatch** — Route the exception to an external system (e.g., JIRA, Slack) for investigation.
API reference: [List exceptions](/en/reference/matcher/list-exceptions) | [Unmatch group](/en/reference/matcher/unmatch-group)
## Example scenario
***
A fintech company reconciles its daily bank statement against internal ledger records.
**Setup:**
* Context: "Daily Bank Reconciliation", type `1:1`, interval `daily`
* Two sources: Chase Bank statement (`BANK`) and General Ledger (`LEDGER`)
* Two rules: Exact match (priority 1) and Tolerance match with 1% and 2-day window (priority 10)
**Daily workflow:**
1. Finance uploads the bank statement and ledger export.
2. Matcher runs a dry run. The preview shows 95% of transactions matched with high confidence.
3. The team reviews the preview and commits the results.
4. Five transactions remain as exceptions: two have small fee differences, three have no counterpart.
5. The team resolves the fee exceptions by creating adjustments. The three missing transactions are escalated for investigation.
## Next steps
***
Full guide to setting up reconciliation contexts.
Deep dive into all rule types and configuration options.
Map different file formats to Matcher's standard schema.
Strategies for handling unmatched transactions.