Contexts and sources

Contexts and sources define how reconciliation is structured in Matcher. A context establishes the reconciliation scope, while sources represent the systems that provide transactional data.

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

Basic context creation

Request

cURL

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

Response

{
  "id":"969a11cd-6b7d-4e71-b82b-0828e0603149",
  "tenantId":"11111111-1111-1111-1111-111111111111",
  "name":"Daily Bank Reconciliation",
  "type":"1:1",
  "interval":"daily",
  "status":"ACTIVE",
  "feeToleranceAbs":"0",
  "feeTolerancePct":"0",
  "createdAt":"2026-02-02T16:31:22Z",
  "updatedAt":"2026-02-02T16:31:22Z"
}

API Reference: Create context

Running reconciliation

Matcher processes transactions through match runs. You can trigger matching manually or view the history of past runs.

Manual match runs

Trigger a match 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"
 }'

Response

{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}

API Reference: Run match

Set mode: "DRY_RUN" to preview results without confirming matches.

Match run modes

Mode	Description
`DRY_RUN`	Preview matches without persisting results
`COMMIT`	Execute matching and persist results

Viewing match run history

cURL

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

Response

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
      "mode": "COMMIT",
      "status": "COMPLETED",
      "startedAt": "2026-01-20T06:00:00Z",
      "completedAt": "2026-01-20T06:05:23Z",
      "createdAt": "2026-01-20T06:00:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}

API Reference: List match runs

Match run statuses

Status	Description
`PENDING`	Run is queued
`PROCESSING`	Run is in progress
`COMPLETED`	Run finished successfully
`FAILED`	Run encountered an error

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

Create a bank source

cURL

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

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "name": "Chase Bank - Account 1234",
  "type": "BANK",
  "config": {},
  "createdAt": "2026-02-02T16:35:00Z",
  "updatedAt": "2026-02-02T16:35:00Z"
}

API Reference: Create source

Create a ledger source

cURL

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

Source types

Type	Description	Typical use
`LEDGER`	General ledger accounts	Internal accounting systems
`BANK`	Bank statements	External bank feeds
`GATEWAY`	Payment processor transactions	Payment gateways
`CUSTOM`	Custom integrations	Any other data source

Source configuration

Sources accept an optional config object for additional metadata:

cURL

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

The config object is flexible and can store any key-value pairs relevant to your integration.

Managing contexts

Update a context

cURL

curl -X PUT "https://api.matcher.example.com/v1/config/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 PUT "https://api.matcher.example.com/v1/config/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

Delete a context

cURL

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

API Reference: Delete 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 reconciliation for a period is complete, the context is Closed, preserving all results and audit records for future reference.

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.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

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

Basic context creation

Request

Response

Running reconciliation

Manual match runs

Response

Match run modes

Viewing match run history

Response

Match run statuses

What is a source?

Adding sources to a context

Create a bank source

Response

Create a ledger source

Source types

Source configuration

Managing contexts

Update a context

Pause a context

Delete a context

Context lifecycle

Best practices

Next steps

Field mapping

Match rules

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​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

​Basic context creation

​Request

​Response

​Running reconciliation

​Manual match runs

​Response

​Match run modes

​Viewing match run history

​Response

​Match run statuses

​What is a source?

​Adding sources to a context

​Create a bank source

​Response

​Create a ledger source

​Source types

​Source configuration

​Managing contexts

​Update a context

​Pause a context

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

Basic context creation

Request

Response

Running reconciliation

Manual match runs

Response

Match run modes

Viewing match run history

Response

Match run statuses

What is a source?

Adding sources to a context

Create a bank source

Response

Create a ledger source

Source types

Source configuration

Managing contexts

Update a context

Pause a context

Delete a context

Context lifecycle

Best practices

Next steps