Contexts and sources

Contexts and sources are how you tell Matcher what to reconcile and where the numbers come from. They are the two building blocks you set up 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 are compared, 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. Get these right and everything downstream — matching, exceptions, and reporting — follows.

What is a reconciliation context?

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

Which data sources are compared
Which matching rules apply
How exceptions are handled
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)

Each transaction is reconciled against a single counterpart. Typical use cases:

Bank statements
Direct payment matching

One-to-many (1:n)

One transaction is reconciled against multiple counterparts. Typical use cases:

Split payments
Batch deposits
Consolidated invoices

Many-to-many (n:m)

Multiple transactions are reconciled 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), how often it runs (interval), and any fee tolerance the comparison should allow. A new context starts in DRAFT so you can add sources and rules before it goes live.

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

Reconciliation frequency (e.g. daily, weekly)

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

default:"NET"

Fee normalization mode: NET or GROSS

boolean

default:"false"

Automatically trigger a match run when a file is uploaded

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 doesn’t 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`	Previews matches without saving anything — use it to validate rule changes safely
`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.

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 pull	Aggregator connections pulled automatically

Fetcher sources

A FETCHER source has its data pulled in automatically instead of being uploaded. 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 connections are set up.

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 stops feeding new data but keeps its full history until you restore it.

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`	Soft-archives the source; it stops feeding new data but is retained.
Restore source	`POST /v1/contexts/{contextId}/sources/{sourceId}/restore`	Reactivates a previously archived source.

API Reference:

Source bindings

Bindings are how a source pulls its own data automatically, so no one has to upload files by hand. A source binding ties a source to the rail that supplies its transactions, plus an interval schedule for how often to pull. Exactly one rail is meaningful per 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.

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": "@every 1h",
   "enabled": true
 }'

Fields

string

required

Rail the source is pulled 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

Interval schedule the binding scheduler reads (cron or @every duration).

boolean

Whether the binding runs immediately. Defaults to true.

API Reference:

Managing contexts

As reconciliations evolve, you’ll 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 stop a context from being used in 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
Can be reversed at any time with the restore endpoint

API Reference: Archive context

Restore a context

Restoring reverses an archive, moving the context from ARCHIVED back to DRAFT so it can be reviewed and reconfigured before being reactivated.

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. This is useful for creating templates or replicating configurations across environments. Cloned fee rules keep referencing the same fee schedules as the source context; the fee schedules themselves are not copied.

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 were copied. The cloned context starts in DRAFT status, so you can review and adjust the configuration before activating it.

API Reference: Clone context

Context lifecycle

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

A context is first created in Draft, where sources and settings are configured.
Once all required sources are in place, the context becomes Active and is eligible for reconciliation runs.
An active context can be temporarily Paused to stop execution without affecting configuration or historical data.
When a context is no longer needed, it can be Archived via 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

This lifecycle ensures operational control, predictable execution, and full traceability across reconciliation periods.

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

Fetcher 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

​Fetcher 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

Fetcher 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