Matcher API quick start

This guide is for developers. If you’re looking for a business-level overview of what Matcher does, see What is Matcher?.

This guide takes you from creating your first reconciliation context to reviewing matched transactions.

Before you begin

You need:

The Matcher API address that Lerian gives you
A valid JWT token for authentication
Two transaction files to reconcile (CSV, JSON, or XML)

All examples use cURL. Replace $TOKEN with your JWT token and https://api.matcher.example.com with the Matcher API address.

Step 1: Create a reconciliation context

A context defines the scope of your reconciliation: what you compare and how.

API reference: Create context

cURL

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

The type field defines how Matcher pairs transactions:

Type	Description
`1:1`	Each transaction matches exactly one counterpart
`1:N`	One transaction can match multiple counterparts
`N:M`	Multiple transactions can match across both sides

Save the id from the response. You will use it in every subsequent step.

{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}

The context starts in DRAFT status. It moves to ACTIVE when you are ready to run reconciliation.

Step 2: Add data sources

To run a match, configure at least two sources: the systems whose transactions you want to compare.

API reference: Create source

Create a bank source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "side": "RIGHT"
 }'

Create a ledger source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "General Ledger - GL 1000",
   "type": "LEDGER",
   "side": "LEFT"
 }'

Save both source id values. Every source needs a side (LEFT or RIGHT): the context reconciles its LEFT sources against its RIGHT sources.

Source types

Type	Use case
`BANK`	Bank statements
`LEDGER`	General ledger / ERP exports
`GATEWAY`	Payment processor data
`CUSTOM`	Any other data source
`FETCHER`	Data extracted through the embedded extraction engine

Step 3: Map source fields

Your source files probably use different column names than Matcher expects. Field maps translate them into Matcher’s standard schema.

API reference: Create field map

Map the bank source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Description"
   }
 }'

Map the ledger source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "entry_id",
     "amount": "debit_credit_amount",
     "currency": "currency_code",
     "date": "posting_date",
     "description": "memo"
   }
 }'

Required fields

Every transaction must have these fields after mapping:

Field	Type	Description
`external_id`	String	Unique identifier within the source
`amount`	Decimal	Transaction amount
`currency`	String	ISO 4217 currency code (e.g. USD)
`date`	Date	Transaction date (YYYY-MM-DD)

Optional: description, fee_amount, fee_currency, and direction. Each mapping key is a Matcher field. Each value is the column name in your file, except for direction. Its value is an object {column, debit, credit} for a file that marks each row as debit or credit in a separate column. A debit row imports with a negative amount, and a credit row with a positive one.

Step 4: Create match rules

Rules define how Matcher compares transactions. Start with an exact rule, which is the most precise.

API reference: Create match rule

Create an exact rule

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'

Add a tolerance rule as fallback

Catch small differences like bank fees or rounding:

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": 20,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'

Matcher evaluates rules by priority (lowest number first). The exact rule runs first. Only unmatched transactions fall through to the tolerance rule.

Rule types

Type	When to use	Priority range
`EXACT`	Values should match exactly	1-1000; unique within the context
`TOLERANCE`	Small, expected differences	1-1000; unique within the context
`DATE_LAG`	Date delays between systems; always proposed for review	1-1000; unique within the context
`FUZZY`	Similarity-scored references; always proposed for review	1-1000; unique within the context

Step 5: Activate the context

Move the context from DRAFT to ACTIVE:

API reference: Update context

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'

If the context is not ready, Matcher refuses the update with 409 Conflict and code MTCH-0103. The errors array of the response lists each missing requirement. Setup progress lists the missing requirements and the next call to make.

Step 6: Upload transaction files

Upload one file per source. Matcher accepts CSV, JSON, and XML formats via multipart form upload.

API reference: Upload transaction file
List ingestion jobs

Upload bank transactions

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_transactions.csv"

Upload ledger transactions

cURL

curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_entries.csv"

Each upload creates an ingestion job. Check the job status:

cURL

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

Wait for both jobs to reach COMPLETED status before running the match.

Step 7: Run matching

Start with a dry run to preview results without persisting:

API reference: Run match

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

The response includes a runId. A dry run saves no match groups. To review its results, read the aggregate statistics of the run with Get match run. When satisfied, run with COMMIT to persist matches:

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

Save the runId from the COMMIT response. You use it in Step 8.

Step 8: Review results

API reference: List match run groups
Unmatch group

View match groups

cURL

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

Each match group contains paired transactions and a confidence score (0-100):

Score	What happens
90-100	Auto-confirmed for EXACT and TOLERANCE matches. FUZZY and DATE_LAG matches need manual review
60-89	Needs manual review

Undo an incorrect match

Use the unmatch endpoint to reject a PROPOSED match group or revoke a CONFIRMED one. Matcher returns the group’s transactions to the unmatched pool for the next run:

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": "Transactions belong to different records"
 }'

Step 9: Handle exceptions

Exceptions are transactions that Matcher could not match automatically. Matcher classifies each exception by severity:

API reference: List exceptions

Severity	Criteria
`CRITICAL`	Amount >= 100,000 or age >= 120h
`HIGH`	Amount >= 10,000 or age >= 72h
`MEDIUM`	Amount >= 1,000 or age >= 24h
`LOW`	All others

List exceptions

cURL

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

Resolve exceptions directly, by force matching, or by creating adjustment entries.

Next steps

Contexts and sources

Full guide to context and source configuration.

Match rules

All rule types and config options in detail.

Confidence scoring

How Matcher calculates scores and what they mean.

Resolving exceptions

Handle unmatched transactions.

​Before you begin

​Step 1: Create a reconciliation context

​Step 2: Add data sources

​Create a bank source

​Create a ledger source

​Source types

​Step 3: Map source fields

​Map the bank source

​Map the ledger source

​Required fields

​Step 4: Create match rules

​Create an exact rule

​Add a tolerance rule as fallback

​Rule types

​Step 5: Activate the context

​Step 6: Upload transaction files

​Upload bank transactions

​Upload ledger transactions

​Step 7: Run matching

​Step 8: Review results

​View match groups

​Undo an incorrect match

​Step 9: Handle exceptions

​List exceptions

​Next steps

Contexts and sources

Match rules

Confidence scoring

Resolving exceptions

Before you begin

Step 1: Create a reconciliation context

Step 2: Add data sources

Create a bank source

Create a ledger source

Source types

Step 3: Map source fields

Map the bank source

Map the ledger source

Required fields

Step 4: Create match rules

Create an exact rule

Add a tolerance rule as fallback

Rule types

Step 5: Activate the context

Step 6: Upload transaction files

Upload bank transactions

Upload ledger transactions

Step 7: Run matching

Step 8: Review results

View match groups

Undo an incorrect match

Step 9: Handle exceptions

List exceptions

Next steps