This guide walks through a complete reconciliation flow using Matcher.
You will define a reconciliation context, configure sources and rules, ingest transaction data, run matching jobs, and review the results.
Prerequisites
Before you begin, ensure you have:
Access to the Matcher API with a valid authentication token
Sample transaction files (provided below)
Sample data
This example reconciles a bank statement against internal ledger records using two CSV files.
Bank_statement.csv
transaction_id,amount,currency,date,reference
BANK-001,1000.00,USD,2024-01-15,Invoice payment
BANK-002,250.50,USD,2024-01-16,Subscription fee
BANK-003,500.00,USD,2024-01-17,Consulting services
BANK-004,75.00,USD,2024-01-18,Office supplies
Ledger_transactions.csv
transaction_id,amount,currency,date,reference
LED-001,1000.00,USD,2024-01-15,Invoice payment
LED-002,250.50,USD,2024-01-16,Monthly subscription
LED-003,500.00,USD,2024-01-17,Consulting services
LED-005,120.00,USD,2024-01-19,Travel expenses
- Three transaction pairs are reconciled
- One bank transaction and one ledger transaction remain unmatched
- Unmatched transactions are created as exceptions
Step 1: create a reconciliation context
Create a reconciliation context to define the reconciliation scope.
Request
curl -X POST https://api.matcher.example.com/v1/contexts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Bank vs Ledger - January 2024",
"type": "1:1",
"description": "Monthly reconciliation of Chase Bank against Main Ledger"
}'
Response
{
"id": "ctx_abc123",
"name": "Bank vs Ledger - January 2024",
"type": "1:1",
"description": "Monthly reconciliation of Chase Bank against Main Ledger",
"created_at": "2024-01-20T10:00:00Z"
}
Store the context ID (ctx_abc123). It is required in subsequent steps.
Step 2: add data sources
Attach the data sources that will be reconciled within this context.
Bank source
Request
curl -X POST https://api.matcher.example.com/v1/contexts/ctx_abc123/sources \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Chase Bank Statement",
"type": "bank",
"field_map": {
"transaction_id": "transaction_id",
"amount": "amount",
"currency": "currency",
"date": "date",
"reference": "reference"
}
}'
Response
{
"id": "src_bank456",
"name": "Chase Bank Statement",
"type": "bank",
"context_id": "ctx_abc123",
"created_at": "2024-01-20T10:01:00Z"
}
Ledger source
Request
curl -X POST https://api.matcher.example.com/v1/contexts/ctx_abc123/sources \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Main Ledger",
"type": "ledger",
"field_map": {
"transaction_id": "transaction_id",
"amount": "amount",
"currency": "currency",
"date": "date",
"reference": "reference"
}
}'
Response
{
"id": "src_ledger789",
"name": "Main Ledger",
"type": "ledger",
"context_id": "ctx_abc123",
"created_at": "2024-01-20T10:02:00Z"
}
Step 3: create a match rule
Define how transactions are compared during reconciliation.
This example applies an exact match on amount, currency, and date.
Request
curl -X POST https://api.matcher.example.com/v1/contexts/ctx_abc123/rules \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Exact Amount and Date",
"type": "EXACT",
"priority": 1,
"parameters": {
"fields": [
"amount",
"currency",
"date"
]
}
}'
Response
{
"id": "rule_exact001",
"name": "Exact Amount and Date",
"type": "EXACT",
"priority": 1,
"context_id": "ctx_abc123",
"created_at": "2024-01-20T10:03:00Z"
}
Step 4: upload transaction files
Upload transaction data for each configured source.
Wait until both ingestion jobs complete before starting the matching job.
Step 5: run the matching job
Start with a dry run to preview reconciliation results without persisting changes.
Dry run
curl -X POST https://api.matcher.example.com/v1/jobs/run \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"context_id": "ctx_abc123",
"mode": "DRY_RUN"
}'
Review results
The dry run returns:
- Proposed matches with confidence scores
- Unmatched transactions classified as exceptions
- A summary of reconciliation effectiveness
Step 6: commit results
If the previewed results are correct, rerun the job using COMMIT mode to finalize reconciliation.
curl -X POST https://api.matcher.example.com/v1/jobs/run \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"context_id": "ctx_abc123",
"mode": "COMMIT"
}'
Understanding results
After reconciliation:
- High-confidence matches are automatically confirmed
- Unmatched transactions are recorded as exceptions
- All actions are persisted in the audit log
You can now review, route, or resolve exceptions as required.
Summary
This quick start covered the complete reconciliation lifecycle:
Context defined
Reconciliation scope established
Sources added
Bank and ledger sources configured
Rules created
Exact matching logic applied
Data ingested
Transaction files uploaded
Matching executed
Dry run reviewed and results committed
Exceptions identified
Unmatched transactions isolated
Next steps
