Split and aggregate matches

Real-world reconciliation often involves transactions that don’t match 1:1. A single payment may cover multiple invoices, or several deposits may consolidate into one bank entry. Matcher handles these complex scenarios through split and aggregate matching.

Overview

The context type controls matching cardinality. Matcher supports three context types:

Context type	Description	Example
1:1 — one to one	One source to one target	Single invoice payment
1:N — one to many / many to one	One source to many targets (split) or many sources to one target (aggregate)	Bulk payment covering invoices; deposits consolidated at a bank
N:M — many to many	Any combination of sources and targets	Complex netting

There is no separate N:1 context type. Aggregate matching (many sources to one target) uses the 1:N context type in the aggregate direction. The same context type covers both split and aggregate.

How it works

Two mechanisms control split and aggregate behavior:

Context type: determines the matching cardinality (1:1, 1:N, or N:M).
Rule allocation flags: control how Matcher distributes amounts within a match group.

There is no separate “split” or “aggregate” setting on the context. The context type defines the allowed patterns, and the rule config controls allocation behavior.

Context type mapping

Context type	Allowed patterns
`1:1`	One source to one target only
`1:N`	One source to many targets (split), or many sources to one target (aggregate)
`N:M`	Any combination of sources and targets

Rule allocation settings

All rule types accept allocation flags in their config:

Field	Type	Description
`allowPartial`	Boolean	Allow partial allocation of transaction amounts
`allocationDirection`	String	Allocation order: `LEFT_TO_RIGHT` or `RIGHT_TO_LEFT`
`allocationToleranceMode`	String	How tolerance is measured: `ABS` (absolute) or `PERCENT`
`allocationToleranceValue`	Decimal	Tolerance threshold for allocation residuals
`allocationUseBaseAmount`	Boolean	Use base (converted) amount for allocation
`feeAware`	Boolean	Fee-aware 1:N allocation: consume each candidate’s gross share (net + fee) instead of net only. Useful for marketplace splits where the payout is net of fees
`nmDeductionBand`	Decimal	TOLERANCE rules only. Short-pay band for the N:M solver, as a decimal fraction of the short invoice face (`0.05` = 5%). Lets a payment subset under-pay an invoice subset within the band. Zero or absent disables it

Example: tolerance rule with allocation

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "matchCurrency": true,
     "allowPartial": true,
     "allocationDirection": "LEFT_TO_RIGHT",
     "allocationToleranceMode": "ABS",
     "allocationToleranceValue": 10.0,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'

Matcher accepts and validates matchScore and matchBaseScore. Both keys remain reserved/inert. They do not change the calculated confidence score. Matcher always computes confidence from the fixed internal component weights (amount 40, currency 30, date 20, reference 10). See Confidence scoring.

Creating a 1:N context

To enable split or aggregate matching, create a context with type 1:N:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Reconciliation",
   "type": "1:N",
   "interval": "daily"
 }'

API Reference: Create context

1:N split matching

One source transaction matches multiple target transactions.

Common use cases

Bulk payment: Single wire covering multiple invoices
Payroll: One bank debit for multiple salary payments
Settlement: One gateway payout for multiple orders

Example: bulk invoice payment

Source (Bank Statement):

ID	Amount	Reference
bank_001	$15,000.00	BULK-PAY-2024-001

Targets (Ledger Entries):

ID	Amount	Invoice
inv_001	$5,000.00	INV-2024-001
inv_002	$7,500.00	INV-2024-002
inv_003	$2,500.00	INV-2024-003

Result: 1:3 match with full allocation

Aggregate matching (many-to-one)

Multiple source transactions match one target transaction. This is the aggregate direction of the 1:N context type. It is not a separate N:1 type.

Common use cases

Bank deposits: Multiple checks deposited as one credit
Card settlements: Daily batch of transactions as one deposit
Cash consolidation: Multiple register receipts to one deposit

Example: consolidated deposit

Sources (Point of Sale):

ID	Amount	Register
pos_001	$1,250.00	REG-01
pos_002	$980.00	REG-02
pos_003	$1,770.00	REG-03

Target (Bank Statement):

ID	Amount	Reference
bank_002	$4,000.00	DEPOSIT-20240120

Result: 3:1 match with full allocation

N:M many-to-many matching

Multiple source transactions match multiple target transactions. This is the most complex pattern.

Common use cases

Intercompany netting: Multiple invoices netted against multiple payments
Trade settlements: Complex clearing with partial fills
Revenue recognition: Multiple deliveries against multiple advances

Example: intercompany netting

Sources (Company A Payables):

ID	Amount	Reference
pay_001	$10,000.00	IC-PAY-001
pay_002	$8,000.00	IC-PAY-002

Targets (Company A Receivables):

ID	Amount	Reference
rec_001	$12,000.00	IC-REC-001
rec_002	$6,000.00	IC-REC-002

Result: 2:2 match, $18,000 total matched To enable N:M matching, create a context with type N:M:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Intercompany Netting",
   "type": "N:M",
   "interval": "weekly"
 }'

Running and reviewing matches

After configuring the context and rules, trigger a matching run and review the resulting groups.

Run matching

cURL

curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'

View match run history

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/contexts/{contextId}/runs" \
 -H "Authorization: Bearer $TOKEN"

View a run’s match groups

You must send the contextId query parameter. The response is a cursor-paginated list of match groups, each containing its matched transactions (across all cardinalities) and confidence scores.

cURL

curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"

Break (unmatch) a match group

To reverse an incorrect group, unmatch it. Matcher rejects a PROPOSED group with a reason, and its transactions return to UNMATCHED. For a CONFIRMED group, Matcher also reverses the residual/open-item effects that confirmation applied, atomically with revoking the group and returning its transactions. You must send the contextId query parameter and a reason in the body.

cURL

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"
 }'

If the confirmed group’s reversal removes the final live contribution behind an obligation, that open item becomes terminal WITHDRAWN. It remains as history, but it is not nettable and no other run carries it. Matcher checks reversibility before changing anything. The endpoint returns 409 Conflict if a later live entry still stands on the residual. It also returns that error if a newer live obligation would conflict with restoring a terminal item on the same identity. In both cases it leaves the group, transactions, and open items unchanged.

Matching algorithm

The algorithm depends on the context type.

1:N deterministic sequential allocation

For split and aggregate (1:N) scenarios, Matcher uses deterministic sequential allocation:

Sort: Matcher sorts transactions deterministically to ensure reproducible results across runs.
Iterate: The engine walks through candidates in priority order.
Allocate: Matcher distributes amounts according to the allocationDirection setting (LEFT_TO_RIGHT or RIGHT_TO_LEFT).
Track residuals: Matcher tracks any remaining unallocated amounts. If allowPartial is true, Matcher caps an overshooting leg to the remaining amount. An under-covered split still surfaces a diagnostic exception.

N:M set-matching solver

For N:M scenarios, Matcher does not allocate sequentially. It uses a bounded subset-selection solver. The solver buckets candidates by the rule’s match identity. It then searches for a subset of left transactions and a subset of right transactions that reconcile against each other. The solver caps cardinality per side. Selection remains deterministic over the sorted input. Each proposed group must clear the fixed confidence gate (minimum score 60). No transaction lands in two proposed groups within a run. On TOLERANCE rules, the nmDeductionBand key lets the solver admit a payment subset that under-pays an invoice subset within the band.

Exception reasons

Transactions that Matcher cannot fully reconcile surface as typed exceptions:

SPLIT_INCOMPLETE: allocations exist but do not fully cover the target amount, regardless of allowPartial.
OVER_SETTLED: a leg over-shot what it settled. Matcher surfaces the over-settled remainder as a typed break.

You can filter the exceptions list by these reason values.

Best practices

Start with 1:N before N:M

Many-to-many matching is complex. Start with simpler patterns and enable N:M only when necessary.

Use allocation tolerance for rounding

Small rounding differences are common in split payments. Set allocationToleranceValue to a few cents to avoid false exceptions.

Enable partial allocation deliberately

Set allowPartial to true only when you expect partial matches. This prevents false matches from incomplete data.

Dry-run before committing

Always test split and aggregate matching in DRY_RUN mode first to verify allocation results.

Monitor residuals

Track residual amounts over time. Growing residuals may indicate systematic matching issues.

Overview

Guides

Matcher UI

MCP Server

Operations

Split and aggregate matches

Overview

How it works

Context type mapping

Rule allocation settings

Example: tolerance rule with allocation

Creating a 1:N context

1:N split matching

Common use cases

Example: bulk invoice payment

Aggregate matching (many-to-one)

Common use cases

Example: consolidated deposit

N:M many-to-many matching

Common use cases

Example: intercompany netting

Running and reviewing matches

Run matching

View match run history

View a run’s match groups

Break (unmatch) a match group

Matching algorithm

1:N deterministic sequential allocation

N:M set-matching solver

Exception reasons

Best practices

Next steps

Match Rules

Security

​Overview

​How it works

​Context type mapping

​Rule allocation settings

​Example: tolerance rule with allocation

​Creating a 1:N context

​1:N split matching

​Common use cases

​Example: bulk invoice payment

​Aggregate matching (many-to-one)

​Common use cases

​Example: consolidated deposit

​N:M many-to-many matching

​Common use cases

​Example: intercompany netting

​Running and reviewing matches

​Run matching

​View match run history

​View a run’s match groups

​Break (unmatch) a match group

​Matching algorithm

​1:N deterministic sequential allocation

​N:M set-matching solver

​Exception reasons

​Best practices

​Next steps

Match Rules

Security

Overview

How it works

Context type mapping

Rule allocation settings

Example: tolerance rule with allocation

Creating a 1:N context

1:N split matching

Common use cases

Example: bulk invoice payment

Aggregate matching (many-to-one)

Common use cases

Example: consolidated deposit

N:M many-to-many matching

Common use cases

Example: intercompany netting

Running and reviewing matches

Run matching

View match run history

View a run’s match groups

Break (unmatch) a match group

Matching algorithm

1:N deterministic sequential allocation

N:M set-matching solver

Exception reasons

Best practices

Next steps