Matcher concepts

The five core concepts in Matcher: contexts, sources, field maps, rules, and matches.

Context

A context defines what you reconcile. It is the configuration container for sources and rules. Its inline sources and rules are optional.

A context answers: what do I match against what?

You can start with an empty draft. To activate it, configure at least one LEFT source and one RIGHT source, map every source (or declare valid camt053 options, which self-map), and add a match rule. If you enable fee normalization, add a fee rule too.

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

The type also fixes the sources per side. A 1:1 context needs exactly one LEFT and one RIGHT source, a 1:N context needs exactly one LEFT source, and an N:M context needs at least one source on each side. A matching run fails when the sources do not fit the type.

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. A draft context can start without sources. An activatable context needs at least one source on each matching side.

Source types

LEDGER: Ledger source category
BANK: Bank source category
GATEWAY: Payment-gateway source category
CUSTOM: Custom source category
FETCHER: A Discovery source category

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 is optional. If you omit it, Matcher stores an empty config and uses parser defaults for absent policy keys. 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	Transaction description
`fee_amount`	No	Decimal	Optional fee amount column
`fee_currency`	No	String	Optional fee currency column
`direction`	No	Object	`{column, debit, credit}`: the column that marks each row as debit or credit. A debit row imports with a negative amount, a credit row with a positive one. CSV, JSON, and XML only

The canonical vocabulary stays closed. Matcher rejects a field map that declares any other key. When you map direction, use an unsigned amount column. Matcher rejects a row with a signed amount, an empty direction cell, or an unknown direction value. When you upload a file with format camt053, Matcher uses its built-in ISO 20022 mapping and ignores the field map. Activation treats a source that declares camt053 options as mapped.

Example mapping

You map a bank statement that exposes TXN_ID, VALUE, CCY, and POST_DATE like this:

{
  "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 ascending priority. A transaction claimed by an earlier rule is unavailable to later rules, which still evaluate the remaining transactions.

Rule types

EXACT: Compares configured fields exactly. Amount, currency, date (by day), and reference are enabled by default.
TOLERANCE: Matches amounts inside the configured absolute and/or percentage tolerance. Currency and reference must also match by default. Omitted amount tolerances and dateWindowDays default to 0, so the rule allows no drift or date window until you configure one.
DATE_LAG: Matches within a configured day-difference band. minDays and maxDays both default to 0 (same day). DATE_LAG only proposes. It never auto-confirms.
FUZZY: Grades normalized transaction references. It uses Reference, populated from the transaction’s ExternalID. A field-map description is not a FUZZY input. FUZZY only proposes. It never auto-confirms, so a human reviews every fuzzy link.

Priority order

Lower numbers run first. A rule claims its matching transactions. Later rules continue with the remaining transactions.

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%

These priorities and values are illustrative rules, not engine defaults. Configure the values for your reconciliation policy.

Rule parameters

Rule type	Parameters
EXACT	`matchAmount`, `matchCurrency`, `matchDate`, `matchReference`: which fields must match exactly
TOLERANCE	Top-level non-negative `percentTolerance` and/or `absTolerance` values (numbers or decimal strings). `percentTolerance` is a fraction: `0.005` is 0.5%. The allowed difference is the larger of `absTolerance` and `percentTolerance` times the larger absolute amount, with the default `percentageBase`. Optionally set `dateWindowDays` (`0` by default; maximum `3650`). Do not wrap these values in a `tolerance` object.
DATE_LAG	`minDays`, `maxDays`: allowed day-difference band. Both default to `0`, must be from `0` to `3650`, and `maxDays` must be at least `minDays`; `inclusive` defaults to `true` and controls both bounds. Amounts must be equal unless you set `feeTolerance`.
FUZZY	`minSimilarity`: normalized-reference threshold from `0` to `1` (defaults to `0.80`), plus amount, currency, and date checks, which are on by default.

Match

A match is when transactions from different sources are reconciled together.

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 `UNMATCHED`

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

N:M match

Multiple transactions on each side are reconciled together. N:M evaluation only executes EXACT and TOLERANCE rules. It considers up to four transactions per side in a group. It skips a candidate bucket that holds more than 40 transactions on a side.

Bank: $100.00 + $200.00 → ERP: $150.00 + $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 records a transaction that needs review, including unmatched transactions and matched transactions with residual conditions such as FX-rate variance.

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. The amount is the absolute value of the transaction’s base amount, or of its amount when it has no base amount. For an aged open item, it is the absolute value of the open balance.

Severity	Default criteria
Critical	Amount ≥ 100,000 or age ≥ 120 hours
High	Amount ≥ 10,000 or age ≥ 72 hours
Medium	Amount ≥ 1,000 or age ≥ 24 hours
Low	All other cases

The classifier evaluates the criteria from top to bottom. When an exception meets the criteria of more than one severity, the highest matching severity applies. Matcher caps an exception with reason FEE_DATA_MISSING at Medium, whatever its amount or age.

Resolution workflows

Resolve: Record a resolution label and optional reason to close an exception.
Force match: Resolve an exception by forcing a match with an override reason and notes after manual review.
Adjust entry: Resolve an exception by creating an adjustment entry with a reason, notes, positive amount, currency, and effective time.

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%	Full weight when the amounts match under the rule or the rule does not check amounts, else `0`
Currency match	30%	Full weight when the currencies match, else `0`
Date tolerance	20%	Full weight when the dates fall inside the rule’s window or the rule does not check dates, else `0`
Reference	10%	Normalized reference alignment (graded 0–1 for FUZZY rules)

Confidence tiers

Tier	Score range	System behavior
Auto-approved	≥ 90	Confirmed automatically for EXACT and TOLERANCE matches. FUZZY and DATE_LAG matches always go to review
Needs review	60–89	Flagged for manual review

Confidence weights and tier thresholds are fixed by the engine. They are not configurable.

Audit log

An audit log is an immutable, append-only record created by an instrumented workflow. It provides traceability for the actions Matcher records.

Logged events

Only workflows instrumented to emit an audit event create entries. Verified producers include:

Context, source, field-map, and rule mutations
Exception workflows, including force match and adjust entry

Audit entry contents

Field	Description
`createdAt`	Record creation timestamp (UTC), which can differ from the audited action time
`actorId`	Actor identifier, when supplied
`action`	Action performed
`entityType`	Affected entity type
`entityId`	Identifier of the affected entity
`changes`	Structured JSON event data; emitted events include `occurred_at` and any supplied changes
`tenantSeq`	Per-tenant sequence number
`prevHash` / `recordHash`	Hash chain linking each entry to the previous one

Audit logs are append-only. Archival exports old monthly partitions to object storage and then drops them from the database.

Overview

Guides

Console

MCP Server

Operations

Matcher concepts

Context

Context types

Example

Source

Source types

Source setup

Field map

Standard fields

Example mapping

Match rule

Rule types

Priority order

Rule parameters

Match

Match status

Match patterns

1:1 match

1:N match

N:1 match

N:M match

Match items

Exception

Exception status

Severity

Resolution workflows

Confidence score

Score calculation

Confidence tiers

Audit log

Logged events

Audit entry contents

Next steps

Architecture

Quick start

​Context

​Context types

​Example

​Source

​Source types

​Source setup

​Field map

​Standard fields

​Example mapping

​Match rule

​Rule types

​Priority order

​Rule parameters

​Match

​Match status

​Match patterns

​1:1 match

​1:N match

​N:1 match

​N:M match

​Match items

​Exception

​Exception status

​Severity

​Resolution workflows

​Confidence score

​Score calculation

​Confidence tiers

​Audit log

​Logged events

​Audit entry contents

​Next steps

Architecture

Quick start

Context

Context types

Example

Source

Source types

Source setup

Field map

Standard fields

Example mapping

Match rule

Rule types

Priority order

Rule parameters

Match

Match status

Match patterns

1:1 match

1:N match

N:1 match

N:M match

Match items

Exception

Exception status

Severity

Resolution workflows

Confidence score

Score calculation

Confidence tiers

Audit log

Logged events

Audit entry contents

Next steps