Contexts and sources

Contexts and sources are how you tell Matcher what to reconcile and where the numbers come from. You set up these two building blocks before any matching happens.

A context is a single reconciliation you care about. For example, “our main bank account vs. our books.” It sets the scope: which systems to compare, which rules apply, and over what period.
A source is one of the systems feeding numbers into that comparison: a bank statement, an ERP export, a payment processor’s settlement file, or a ledger.

Every context compares exactly two sides against each other, so each one needs at least two sources. Matching, exceptions, and reporting all depend on these two.

What is a reconciliation context?

A reconciliation context defines the operational boundaries of a reconciliation process. It specifies:

Which data sources to compare
Which matching rules apply
How to handle exceptions
The time window covered by reconciliation

Common examples:

Bank Account 1234 vs General Ledger (daily bank reconciliation)
Payment Gateway vs Revenue System (payment reconciliation)
Intercompany Entity A vs Entity B (intercompany reconciliation)

Context types

Matcher lets you use different reconciliation cardinalities based on transaction structure.

One-to-one (1:1)

Matcher reconciles each transaction against a single counterpart. Typical use cases:

Bank statements
Direct payment matching

One-to-many (1:n)

Matcher reconciles one transaction against multiple counterparts. Typical use cases:

Split payments
Batch deposits
Consolidated invoices

Many-to-many (n:m)

Matcher reconciles multiple transactions across multiple counterparts. Typical use cases:

Netting arrangements
Complex payment allocation
Multi-leg financial flows

Creating a reconciliation context

Once you know what you’re reconciling, create the context. At this stage you’re mainly declaring the cardinality (type), a required execution label (interval), and any fee tolerance the comparison should allow. The interval value does not schedule runs. Automatic execution requires a separate reconciliation schedule. A new context starts in DRAFT and remains there until you explicitly activate it.

Request

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",
   "interval": "daily",
   "type": "1:1",
   "feeToleranceAbs": "0",
   "feeTolerancePct": "0",
   "feeNormalization": "NET",
   "autoMatchOnUpload": false
 }'

Context fields

string

Descriptive name for the context

string

Matching cardinality: 1:1, 1:N, or N:M

string

Required execution label (e.g. daily, weekly). It does not schedule runs.

string

default:"0"

Absolute fee tolerance for amount comparison, as a decimal string (e.g. "0.01")

string

default:"0"

Percentage fee tolerance for amount comparison, as a decimal string ("0.5" means 0.5%)

string

Optional fee normalization mode: NET or GROSS. Omit it to leave fee normalization disabled.

boolean

default:"false"

Automatically trigger a match run after a file upload

Response

{
  "id":"019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "tenantId":"11111111-1111-1111-1111-111111111111",
  "name":"Daily Bank Reconciliation",
  "type":"1:1",
  "interval":"daily",
  "status":"DRAFT",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "feeNormalization":"NET",
  "autoMatchOnUpload":false,
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

API Reference: Create context

Running reconciliation

A context does not reconcile on its own. You trigger a match run. A run applies the context’s active rules to the transactions in its sources, then produces matches and exceptions. You can trigger runs by hand, or let a schedule fire them automatically. Every run works in one of two modes:

Mode	What it does
`DRY_RUN`	Does not persist matching results, transaction mutations, fee artifacts, or exceptions, but does persist a completed `MatchRun` and its statistics
`COMMIT`	Executes matching and persists the results

Trigger a run for a context:

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

By default a run is synchronous: it executes in-request and the response carries the final status. For large volumes, set "async": true to submit the run and poll its progress instead. Asynchronous submission requires an enabled match-run worker. Without one, Matcher rejects "async": true with HTTP 503.

Both modes return HTTP 202 Accepted, so read the response status, not the HTTP code, to know the outcome.A synchronous run returns a terminal COMPLETED or FAILED. An async run returns QUEUED, and you poll GET /v1/matching/runs/{runId}.While in flight, a run moves through PROCESSING and FINALIZING (treat both as not-yet-done) before reaching COMPLETED or FAILED.

To review past runs, list a context’s run history with GET /v1/matching/contexts/{contextId}/runs.

API Reference:

What is a source?

A source represents a system or data feed that supplies transactions to a reconciliation context. Each context requires at least two sources. Typical sources include:

Bank statement feeds
ERP general ledger exports
Payment processor transaction streams
Internal accounting systems

Adding sources to a context

A context needs at least two sources, one for each side of the comparison. The side field (LEFT or RIGHT) declares which side a source feeds. Matcher reconciles the LEFT side against the RIGHT side. Assign one side to each source and keep the assignment consistent. Create a source with a name, type, side, and a config object. Leave config empty ({}) when the source needs no connection-specific settings, as with a bank feed on the LEFT side:

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": "LEFT",
   "config": {}
 }'

Point the other side at a second source. config carries source-specific connection and parsing settings when they’re needed, for example a payment gateway on the RIGHT side:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Payment Gateway",
   "type": "GATEWAY",
   "side": "RIGHT",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

name, type, and side are required (name is 1–50 characters). config is optional and defaults to an empty object when omitted.

API Reference: Create source

Source types

Type	Description	Typical use
`LEDGER`	Internal ledger	Internal accounting systems (including Midaz)
`BANK`	Bank statement feed	External bank feeds
`GATEWAY`	Payment gateway	Payment processors (Stripe, Adyen, PayPal)
`CUSTOM`	Bespoke feed	Any other data source
`FETCHER`	Discovery-engine source	Aggregator connections supplied through a source binding

Discovery sources

FETCHER identifies a source type. It does not enable automatic pulling by itself. Create it like any other source, then wire the upstream aggregator connection through a source binding on the query rail (connectionId). See Discovery for how to set up connections.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Open Banking Aggregator",
   "type": "FETCHER",
   "side": "LEFT",
   "config": {
     "provider": "pluggy"
   }
 }'

Managing sources

Sources support a full CRUD lifecycle under /v1/contexts/{contextId}/sources. You can rename or reconfigure a source at any time, and archiving is soft and reversible. An archived source is excluded from context readiness, matching, and source listings, but keeps its full history until you restore it. Archiving does not disable its bindings. Disable or delete them separately to stop scheduler dispatch.

Action	Method & path	Notes
Create source	`POST /v1/contexts/{contextId}/sources`	Body: `name`, `type`, `side`, `config` (see above).
List sources	`GET /v1/contexts/{contextId}/sources`	Lists sources in the context.
Get source	`GET /v1/contexts/{contextId}/sources/{sourceId}`	Retrieves a single source by id.
Update source	`PATCH /v1/contexts/{contextId}/sources/{sourceId}`	Updates mutable source fields (e.g. `name`, `config`).
Archive source	`POST /v1/contexts/{contextId}/sources/{sourceId}/archive`	Excludes the source from readiness, matching, and listings; bindings remain enabled until changed separately.
Restore source	`POST /v1/contexts/{contextId}/sources/{sourceId}/restore`	Reactivates a previously archived source.

API Reference:

Source bindings

Bindings define how the binding scheduler can pull source data without a manual file upload. A source binding ties a source to the rail that supplies its transactions, plus a duration that determines when it is due. Exactly one rail applies to each binding kind:

file: fetches files via a transport (populates transportConfig).
query: pulls rows through a discovery-engine connection (populates connectionId). See Discovery.

Bindings live under /v1/contexts/{contextId}/sources/{sourceId}/bindings.

A binding is dispatched only when the binding scheduler is enabled (it is disabled by default), the binding is enabled, and the binding is due. Creating or enabling a binding does not run it immediately.

Action	Method & path
Create binding	`POST /v1/contexts/{contextId}/sources/{sourceId}/bindings`
List bindings	`GET /v1/contexts/{contextId}/sources/{sourceId}/bindings`
Get binding	`GET /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`
Update binding	`PATCH /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`
Delete binding	`DELETE /v1/contexts/{contextId}/sources/{sourceId}/bindings/{bindingId}`

List returns every binding, enabled and disabled, so a disabled binding stays visible instead of silently vanishing.

Create a query-rail binding

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/bindings" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "kind": "query",
   "connectionId": "550e8400-e29b-41d4-a716-446655440000",
   "format": "br/cnab400/default",
   "scheduleSpec": "1h",
   "enabled": true
 }'

Fields

string

required

Rail the scheduler pulls the source on: file or query (required).

string (UUID)

Query-rail discovery-engine connection. Required for query, rejected for file.

string

Declared format the binding produces (region/family-namespaced descriptor key, e.g. br/cnab400/default).

string

Go duration string the binding scheduler reads, such as 1h or 30m. Cron and @every syntax are invalid.

boolean

Whether the scheduler can dispatch the binding when it is due. Defaults to true. Enabling it does not run it immediately.

API Reference:

Managing contexts

You can adjust a context’s settings, pause it, retire it, or copy it. These lifecycle operations preserve history so you never lose an audit trail.

Update a context

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation - Updated",
   "interval": "weekly",
   "status": "PAUSED"
 }'

API Reference: Update context

Pause a context

To temporarily keep a context out of reconciliation runs, update its status to PAUSED:

cURL

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

Pausing a context:

Prevents new match runs
Preserves historical data
Allows future reactivation by setting status back to ACTIVE

Archive a context

Archiving is a reversible soft-delete. Instead of permanently removing a context, it moves the context to the ARCHIVED status, preserving its full history (sources, rules, match runs, and audit records) while excluding it from the default context listing.

cURL

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

Archiving a context:

Sets the context status to ARCHIVED
Preserves the complete history and audit trail
Excludes the context from the default listing
Is reversible at any time with the restore endpoint

API Reference: Archive context

Restore a context

Restoring reverses an archive. It moves the context from ARCHIVED back to DRAFT, so you can review and reconfigure the context before you reactivate it.

cURL

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

Restoring a context:

Sets the context status from ARCHIVED back to DRAFT
Does not resume matching automatically. Review and reactivate the context to run reconciliation again
Returns 409 Conflict if called on a context that is not archived

API Reference: Restore context

Clone a context

To duplicate an existing context with its sources, rules, fee rules, and field maps, use the clone endpoint. Use it to create templates or replicate configurations across environments. Cloned fee rules keep referencing the same fee schedules as the source context. Matcher does not copy the fee schedules themselves.

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/clone" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Q1 2025 Reconciliation (Copy)",
   "includeSources": true,
   "includeRules": true
 }'

The response reports how many sources, rules, fee rules, and field maps Matcher copied. A successful clone returns in ACTIVE status.

API Reference: Clone context

Context lifecycle

A reconciliation context follows a lifecycle that controls when matching can run and how data is preserved.

A context starts in Draft, where you configure sources and settings.
A context remains Draft until an explicit update sets it to ACTIVE. Activation validates the required sources on both LEFT and RIGHT sides, field mappings or CAMT options, match rules, and fee rules when you enable fee normalization.
An active context can be temporarily Paused to stop execution without affecting configuration or historical data.
When you no longer need a context, move it to Archived with the archive endpoint. Archiving is a reversible soft-delete: it moves the context to ARCHIVED, preserves the full history and audit records, and excludes it from the default listing. An archived context can be brought back to Draft at any time with the restore endpoint.

Matcher Context Lifecycle — Lifecycle of a Matcher context

Best practices

Use descriptive names

Use explicit names that reflect accounts, systems, and purpose.

Start with conservative thresholds

Favor accuracy over automation initially. Adjust thresholds based on observed results.

Separate concerns

Use multiple contexts instead of a single broad reconciliation.

Flag regulatory sources

Always mark sources with compliance requirements.

Align timezones

Ensure source timezones reflect the original data feed.

Document sign conventions

Explicitly define debit and credit semantics for each source.

Next steps

Field mapping

Define how source fields map to Matcher’s schema.

Match rules

Configure the rules that drive reconciliation.

Overview

Guides

Matcher UI

MCP Server

Operations

Contexts and sources

What is a reconciliation context?

Context types

One-to-one (1:1)

One-to-many (1:n)

Many-to-many (n:m)

Creating a reconciliation context

Request

Context fields

Response

Running reconciliation

What is a source?

Adding sources to a context

Source types

Discovery sources

Managing sources

Source bindings

Create a query-rail binding

Fields

Managing contexts

Update a context

Pause a context

Archive a context

Restore a context

Clone a context

Context lifecycle

Best practices

Next steps

Field mapping

Match rules

​What is a reconciliation context?

​Context types

​One-to-one (1:1)

​One-to-many (1:n)

​Many-to-many (n:m)

​Creating a reconciliation context

​Request

​Context fields

​Response

​Running reconciliation

​What is a source?

​Adding sources to a context

​Source types

​Discovery sources

​Managing sources

​Source bindings

​Create a query-rail binding

​Fields

​Managing contexts

​Update a context

​Pause a context

​Archive a context

​Restore a context

​Clone a context

​Context lifecycle

​Best practices

​Next steps

Field mapping

Match rules

What is a reconciliation context?

Context types

One-to-one (1:1)

One-to-many (1:n)

Many-to-many (n:m)

Creating a reconciliation context

Request

Context fields

Response

Running reconciliation

What is a source?

Adding sources to a context

Source types

Discovery sources

Managing sources

Source bindings

Create a query-rail binding

Fields

Managing contexts

Update a context

Pause a context

Archive a context

Restore a context

Clone a context

Context lifecycle

Best practices

Next steps