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

Matcher lets you four matching patterns:

Pattern	Description	Example
1:1	One source to one target	Single invoice payment
1:N	One source to many targets	Bulk payment covering invoices
N:1	Many sources to one target	Deposits consolidated at bank
N:M	Many sources to many targets	Complex netting

Enabling complex matching

Context configuration

Enable split and aggregate matching at the context level:

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/ctx_abc123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "settings": {
     "matching": {
       "allow_split": true,
       "allow_aggregate": true,
       "allow_many_to_many": false,
       "max_transactions_per_group": 20,
       "require_full_allocation": true
     }
   }
 }'

Response

{
  "id": "ctx_abc123",
  "name": "Payment Reconciliation",
  "settings": {
    "matching": {
      "allow_split": true,
      "allow_aggregate": true,
      "allow_many_to_many": false,
      "max_transactions_per_group": 20,
      "require_full_allocation": true
    }
  }
}

Matching settings

Setting	Type	Default	Description
`allow_split`	Boolean	false	Enable 1:N matching
`allow_aggregate`	Boolean	false	Enable N:1 matching
`allow_many_to_many`	Boolean	false	Enable N:M matching
`max_transactions_per_group`	Integer	10	Maximum transactions in a group
`require_full_allocation`	Boolean	true	Require 100% allocation
`partial_match_threshold`	Decimal	0.95	Minimum allocation for partial (95%)

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

API: create split match

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "SPLIT",
   "source_transactions": [
     {
       "transaction_id": "bank_001",
       "amount": 15000.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "inv_001",
       "allocated_amount": 5000.0
     },
     {
       "transaction_id": "inv_002",
       "allocated_amount": 7500.0
     },
     {
       "transaction_id": "inv_003",
       "allocated_amount": 2500.0
     }
   ]
 }'

Response

{
  "match_id": "match_split_001",
  "type": "SPLIT",
  "status": "PROPOSED",
  "confidence": 95,
  "source": {
    "transaction_count": 1,
    "total_amount": 15000.0,
    "allocated_amount": 15000.0,
    "allocation_percent": 100.0
  },
  "targets": {
    "transaction_count": 3,
    "total_amount": 15000.0,
    "allocated_amount": 15000.0,
    "allocation_percent": 100.0
  },
  "residual": 0.0,
  "transactions": [
    {
      "id": "bank_001",
      "role": "SOURCE",
      "amount": 15000.0,
      "allocated": 15000.0
    },
    {
      "id": "inv_001",
      "role": "TARGET",
      "amount": 5000.0,
      "allocated": 5000.0
    },
    {
      "id": "inv_002",
      "role": "TARGET",
      "amount": 7500.0,
      "allocated": 7500.0
    },
    {
      "id": "inv_003",
      "role": "TARGET",
      "amount": 2500.0,
      "allocated": 2500.0
    }
  ],
  "created_at": "2024-01-20T10:00:00Z"
}

N:1 aggregate matching

Multiple source transactions match one target transaction.

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

API: create aggregate match

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "AGGREGATE",
   "source_transactions": [
     {
       "transaction_id": "pos_001",
       "allocated_amount": 1250.0
     },
     {
       "transaction_id": "pos_002",
       "allocated_amount": 980.0
     },
     {
       "transaction_id": "pos_003",
       "allocated_amount": 1770.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "bank_002",
       "amount": 4000.0
     }
   ]
 }'

Response

{
  "match_id": "match_agg_001",
  "type": "AGGREGATE",
  "status": "PROPOSED",
  "confidence": 92,
  "source": {
    "transaction_count": 3,
    "total_amount": 4000.0,
    "allocated_amount": 4000.0,
    "allocation_percent": 100.0
  },
  "targets": {
    "transaction_count": 1,
    "total_amount": 4000.0,
    "allocated_amount": 4000.0,
    "allocation_percent": 100.0
  },
  "residual": 0.0
}

N:M many-to-many matching

Multiple source transactions match multiple target transactions. This is the most complex pattern and requires the graph solver.

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

API: create N:M match

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/matches" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "MANY_TO_MANY",
   "source_transactions": [
     {
       "transaction_id": "pay_001",
       "allocated_amount": 10000.0
     },
     {
       "transaction_id": "pay_002",
       "allocated_amount": 8000.0
     }
   ],
   "target_transactions": [
     {
       "transaction_id": "rec_001",
       "allocated_amount": 12000.0
     },
     {
       "transaction_id": "rec_002",
       "allocated_amount": 6000.0
     }
   ]
 }'

Allocation tracking

Matcher tracks how much of each transaction has been allocated to matches.

Transaction allocation status

Status	Description
`UNALLOCATED`	No allocation (0%)
`PARTIALLY_ALLOCATED`	Some allocation (1-99%)
`FULLY_ALLOCATED`	Complete allocation (100%)

View transaction allocation

curl -X GET "https://api.matcher.example.com/v1/transactions/bank_001/allocation" \
 -H "Authorization: Bearer $TOKEN"

Response

{
  "transaction_id": "bank_001",
  "total_amount": 15000.0,
  "currency": "USD",
  "allocation_status": "FULLY_ALLOCATED",
  "allocations": [
    {
      "match_id": "match_split_001",
      "allocated_amount": 15000.0,
      "allocation_percent": 100.0,
      "status": "CONFIRMED"
    }
  ],
  "available_amount": 0.0,
  "available_percent": 0.0
}

Partial allocation example

Transaction with remaining unallocated amount:

{
  "transaction_id": "bank_003",
  "total_amount": 10000.0,
  "allocation_status": "PARTIALLY_ALLOCATED",
  "allocations": [
    {
      "match_id": "match_002",
      "allocated_amount": 7500.0,
      "allocation_percent": 75.0,
      "status": "CONFIRMED"
    }
  ],
  "available_amount": 2500.0,
  "available_percent": 25.0
}

Partial matches

By default, Matcher requires full allocation. Enable partial matching for scenarios where complete matching isn’t possible.

Enable partial matching

{
  "settings": {
    "matching": {
      "require_full_allocation": false,
      "partial_match_threshold": 0.9,
      "partial_match_behavior": "propose_with_residual"
    }
  }
}

Partial match behaviors

Behavior	Description
`propose_with_residual`	Create match, track residual
`create_exception`	Create exception for unmatched portion
`hold_for_review`	Hold until additional transactions arrive

Partial match response

{
  "match_id": "match_partial_001",
  "type": "SPLIT",
  "status": "PROPOSED",
  "confidence": 78,
  "source": {
    "total_amount": 10000.0,
    "allocated_amount": 9500.0,
    "allocation_percent": 95.0
  },
  "targets": {
    "total_amount": 9500.0,
    "allocated_amount": 9500.0,
    "allocation_percent": 100.0
  },
  "residual": {
    "amount": 500.0,
    "percent": 5.0,
    "status": "UNALLOCATED",
    "exception_id": "exc_residual_001"
  }
}

Graph solver

For complex N:M scenarios, Matcher uses a bipartite graph solver to find optimal matches.

How it works

Build Graph: Create bipartite graph with sources and targets as nodes
Edge Weights: Calculate match confidence as edge weights
Solve: Find maximum weighted matching
Allocate: Distribute amounts across matched pairs

Graph solver configuration

{
  "settings": {
    "graph_solver": {
      "enabled": true,
      "algorithm": "hungarian",
      "max_nodes": 100,
      "min_edge_confidence": 50,
      "optimization_goal": "maximize_allocation"
    }
  }
}

Solver algorithms

Algorithm	Best For	Complexity
`hungarian`	Small graphs (<100 nodes)	O(n³)
`auction`	Medium graphs (<1000 nodes)	O(n² log n)
`greedy`	Large graphs (>1000 nodes)	O(n log n)

Run graph solver

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/solve" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "source_transactions": [
     "pay_001",
     "pay_002",
     "pay_003"
   ],
   "target_transactions": [
     "rec_001",
     "rec_002",
     "rec_003"
   ],
   "options": {
     "algorithm": "hungarian",
     "allow_partial": true,
     "min_confidence": 60
   }
 }'

Response

{
  "solver_id": "solve_001",
  "status": "COMPLETED",
  "algorithm": "hungarian",
  "execution_time_ms": 45,
  "results": {
    "proposed_matches": [
      {
        "match_id": "match_proposed_001",
        "type": "MANY_TO_MANY",
        "confidence": 88,
        "allocations": [
          {
            "source": "pay_001",
            "target": "rec_001",
            "amount": 10000.0
          },
          {
            "source": "pay_002",
            "target": "rec_001",
            "amount": 2000.0
          },
          {
            "source": "pay_002",
            "target": "rec_002",
            "amount": 6000.0
          }
        ]
      }
    ],
    "unmatched_sources": [],
    "unmatched_targets": [],
    "total_matched": 18000.0,
    "match_rate": 100.0
  }
}

Tolerance rules

Configure how tolerance applies to split and aggregate matches.

Tolerance modes

Mode	Description	Use Case
`residual`	Apply to final unmatched amount	Default, most common
`per_item`	Apply to each transaction	Strict matching
`total`	Apply to sum of all transactions	Flexible matching

Configure tolerance mode

{
  "settings": {
    "matching": {
      "tolerance_mode": "residual",
      "tolerance_percent": 1.0,
      "tolerance_absolute": 50.0
    }
  }
}

Tolerance examples

Residual Mode (Default):

Source: $10,000.00
Targets: $9,980.00 total
Residual: $20.00 (0.2%)
Tolerance: 1% = $100.00
Result: Match (residual within tolerance)

Per-Item Mode:

Source: $10,000.00
Target 1: $5,010.00 (0.2% variance)
Target 2: $4,980.00 (0.4% variance)
Each within 1% tolerance
Result: Match (all items within tolerance)

Auto-discovery

Matcher can automatically discover split and aggregate patterns.

Enable auto-discovery

{
  "settings": {
    "auto_discovery": {
      "enabled": true,
      "max_group_size": 10,
      "time_window_days": 7,
      "min_confidence": 75
    }
  }
}

Discovery heuristics

Heuristic	Description
Amount summing	Find combinations that sum to target
Reference patterns	Match based on common references
Temporal clustering	Group transactions by date proximity
Counterparty grouping	Group by same counterparty

View discovered groups

curl -X GET "https://api.matcher.example.com/v1/contexts/ctx_abc123/discoveries" \
 -H "Authorization: Bearer $TOKEN"

Response

{
  "discoveries": [
    {
      "id": "disc_001",
      "type": "AGGREGATE",
      "confidence": 85,
      "heuristic": "amount_summing",
      "source_transactions": [
        "pos_001",
        "pos_002",
        "pos_003"
      ],
      "target_transactions": [
        "bank_002"
      ],
      "source_total": 4000.0,
      "target_total": 4000.0,
      "residual": 0.0
    }
  ]
}

Reporting

Group match summary

curl -X GET "https://api.matcher.example.com/v1/contexts/ctx_abc123/reports/group-matches" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "date_from=2024-01-01" \
 -d "date_to=2024-01-31"

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "summary": {
    "total_matches": 1250,
    "by_type": {
      "one_to_one": 980,
      "split": 150,
      "aggregate": 100,
      "many_to_many": 20
    },
    "avg_group_size": {
      "split": 3.2,
      "aggregate": 4.5,
      "many_to_many": 6.1
    },
    "partial_matches": 45,
    "total_residual": 12500.0
  }
}

Best practices

Start with 1:N and N:1 before N:M

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

Set reasonable group size limits

Large groups are harder to verify. Limit group size based on your audit requirements.

Use auto-discovery with review

Enable auto-discovery to find patterns, but require human review before confirming complex matches.

Monitor residuals

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

Document allocation rules

When multiple allocation strategies are possible, document why specific allocations were chosen.

Test graph solver with sample data

Before enabling graph solver in production, test with representative data to verify results.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​Overview

​Enabling complex matching

​Context configuration

​Response

​Matching settings

​1:N split matching

​Common use cases

​Example: bulk invoice payment

​API: create split match

​Response

​N:1 aggregate matching

​Common use cases

​Example: consolidated deposit

​API: create aggregate match

​Response

​N:M many-to-many matching

​Common use cases

​Example: intercompany netting

​API: create N:M match

​Allocation tracking

​Transaction allocation status

​View transaction allocation

​Response

​Partial allocation example

​Partial matches

​Enable partial matching

​Partial match behaviors

​Partial match response

​Graph solver

​How it works

​Graph solver configuration

​Solver algorithms

​Run graph solver

​Response

​Tolerance rules

​Tolerance modes

​Configure tolerance mode

​Tolerance examples

​Auto-discovery

​Enable auto-discovery

​Discovery heuristics

​View discovered groups

​Response

​Reporting

​Group match summary

​Best practices

​Next steps

Match Rules

Security

Overview

Enabling complex matching

Context configuration

Response

Matching settings

1:N split matching

Common use cases

Example: bulk invoice payment

API: create split match

Response

N:1 aggregate matching

Common use cases

Example: consolidated deposit

API: create aggregate match

Response

N:M many-to-many matching

Common use cases

Example: intercompany netting

API: create N:M match

Allocation tracking

Transaction allocation status

View transaction allocation

Response

Partial allocation example

Partial matches

Enable partial matching

Partial match behaviors

Partial match response

Graph solver

How it works

Graph solver configuration

Solver algorithms

Run graph solver

Response

Tolerance rules

Tolerance modes

Configure tolerance mode

Tolerance examples

Auto-discovery

Enable auto-discovery

Discovery heuristics

View discovered groups

Response

Reporting

Group match summary

Best practices

Next steps