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

Matching cardinality is controlled by the context type. 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) is simply the 1:N context type applied in the aggregate direction — the same context type covers both split and aggregate.

How it works

Split and aggregate behavior is controlled by two mechanisms:

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

There is no separate “split” or “aggregate” setting on the context. The context type defines what patterns are allowed, 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
   }
 }'

matchScore and matchBaseScore are accepted and validated but reserved/inert — they do not change the calculated confidence score. Confidence is always computed 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

The contextId query parameter is required. 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. This rejects the group with a reason and reverts all of its transactions to UNMATCHED. The contextId query parameter is required, and a reason is sent 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"
 }'

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: Transactions are sorted deterministically to ensure reproducible results across runs.
Iterate: The engine walks through candidates in priority order.
Allocate: Amounts are distributed according to the allocationDirection setting (LEFT_TO_RIGHT or RIGHT_TO_LEFT).
Track residuals: Any remaining unallocated amounts are tracked. If allowPartial is true, an overshooting leg is capped 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: candidates are bucketed by the rule’s match identity, and the solver searches for a subset of left transactions and a subset of right transactions that reconcile against each other, with cardinality capped per side. Selection is deterministic over the sorted input, each proposed group must clear the fixed confidence gate (minimum score 60), and 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 cannot be fully reconciled 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 was settling; the over-settled remainder is surfaced 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

Only set allowPartial to true when partial matches are expected. 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