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

Context fields

Field	Type	Default	Description
`name`	String	—	Descriptive name for the context
`type`	String	—	Matching cardinality: `1:1`, `1:N`, or `N:M`
`interval`	String	—	Reconciliation frequency (e.g. `daily`, `weekly`)
`rateId`	String	`""`	Reference to an FX rate configuration for multi-currency matching
`feeToleranceAbs`	Decimal	`0`	Absolute fee tolerance for amount comparison
`feeTolerancePct`	Decimal	`0`	Percentage fee tolerance for amount comparison
`feeNormalization`	String	`"NET"`	Fee normalization mode: `NET` or `GROSS`
`autoMatchOnUpload`	Boolean	`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",
  "rateId":"",
  "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

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, and an optional feeScheduleId to associate a fee schedule:

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",
   "feeScheduleId": "",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'

Field	Type	Description
`name`	String	Descriptive name for the source
`type`	String	Source type: `LEDGER`, `BANK`, `GATEWAY`, or `CUSTOM`
`feeScheduleId`	String	Optional reference to a fee schedule for this source
`config`	Object	Flexible key-value pairs for integration metadata

Managing contexts

Update a context

cURL

curl -X PATCH "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 PATCH "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

Clone a context

To duplicate an existing context with its sources, rules, and fee schedules, use the clone endpoint. This is useful for creating templates or replicating configurations across environments.

cURL

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

Response

{
  "context": {
    "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
    "name": "Q1 2025 Reconciliation (Copy)",
    "type": "1:1",
    "status": "DRAFT"
  },
  "sourcesCloned": 3,
  "rulesCloned": 5,
  "fieldMapsCloned": 3,
  "feeSchedulesCloned": 2
}

API Reference: Clone context

The cloned context starts in DRAFT status, so you can review and adjust the configuration before activating it.

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 Archived, 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

​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

​Context fields

​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

​Clone a context

​Response

​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

Context fields

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

Clone a context

Response

Context lifecycle

Best practices

Next steps