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 context

Basic context creation

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",
   "description": "Chase Bank account 1234 vs Main Ledger GL 1000",
   "type": "ONE_TO_ONE",
   "tenant_id": "tenant_001",
   "settings": {
     "date_tolerance_days": 3,
     "auto_confirm_threshold": 90,
     "review_threshold": 60
   }
 }'

Response

{
  "id": "ctx_abc123",
  "name": "Daily Bank Reconciliation",
  "description": "Chase Bank account 1234 vs Main Ledger GL 1000",
  "type": "ONE_TO_ONE",
  "tenant_id": "tenant_001",
  "status": "ACTIVE",
  "settings": {
    "date_tolerance_days": 3,
    "auto_confirm_threshold": 90,
    "review_threshold": 60
  },
  "sources": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T10:00:00Z"
}

Context settings

Setting	Type	Default	Description
`date_tolerance_days`	Integer	3	Maximum allowed date difference
`auto_confirm_threshold`	Integer	90	Confidence score required for auto-confirmation
`review_threshold`	Integer	60	Minimum score to propose a match
`allow_partial_match`	Boolean	false	Allow partial amount matching
`require_currency_match`	Boolean	true	Enforce currency consistency
`enable_many_to_many`	Boolean	false	Enable N:M reconciliation

Automatic match scheduling

Matcher can run matching jobs automatically at scheduled intervals. Once configured, the system will process all available transactions from your sources at the defined frequency.

Schedule configuration

Configure automatic scheduling when creating or updating a context:

{
  "schedule": {
    "enabled": true,
    "frequency": "daily",
    "time": "06:00",
    "timezone": "UTC",
    "on_weekends": false,
    "retry_on_failure": true,
    "max_retries": 3
  }
}

Schedule frequencies

Frequency	Description	Typical Use Case
`hourly`	Every hour at minute :00	Real-time payment reconciliation
`daily`	Once per day at specified time	Bank statement reconciliation
`weekly`	Once per week on specified day	Weekly treasury reports
`monthly`	First day of month at specified time	Month-end close reconciliation
`custom`	Cron expression	Complex scheduling needs

Custom schedules

For advanced scheduling, use cron expressions:

{
  "schedule": {
    "enabled": true,
    "frequency": "custom",
    "cron": "0 6,18 * * 1-5",
    "timezone": "America/New_York"
  }
}

Common cron patterns:

0 6 * * * - Daily at 6:00 AM
0 6,18 * * 1-5 - Twice daily (6 AM, 6 PM) on weekdays
0 0 1 * * - Monthly on the 1st at midnight
0 */4 * * * - Every 4 hours

Match run behavior

When a scheduled match runs:

Ingestion check: Verifies all sources have recent data
Transaction retrieval: Pulls unmatched transactions from all sources
Rule application: Applies match rules in priority order
Confidence scoring: Calculates confidence for each proposed match
Auto-confirmation: Confirms matches above the auto-confirm threshold
Exception creation: Creates exceptions for unmatched items
Notification: Sends alerts based on notification settings

Viewing match run history

cURL

curl -X GET "https://api.matcher.example.com/v1/contexts/ctx_abc123/match-runs" \
 -H "Authorization: Bearer $TOKEN" \
 -G \
 -d "date_from=2024-01-01" \
 -d "date_to=2024-01-31"

Response

{
  "match_runs": [
    {
      "id": "run_001",
      "context_id": "ctx_abc123",
      "status": "COMPLETED",
      "trigger": "SCHEDULED",
      "started_at": "2024-01-20T06:00:00Z",
      "completed_at": "2024-01-20T06:05:23Z",
      "duration_seconds": 323,
      "statistics": {
        "transactions_processed": 1250,
        "matches_found": 1180,
        "matches_confirmed": 1120,
        "matches_pending_review": 60,
        "exceptions_created": 70
      }
    },
    {
      "id": "run_002",
      "context_id": "ctx_abc123",
      "status": "COMPLETED",
      "trigger": "MANUAL",
      "started_at": "2024-01-19T06:00:00Z",
      "completed_at": "2024-01-19T06:04:51Z",
      "duration_seconds": 291,
      "statistics": {
        "transactions_processed": 1198,
        "matches_found": 1145,
        "matches_confirmed": 1090,
        "matches_pending_review": 55,
        "exceptions_created": 53
      }
    }
  ],
  "pagination": {
    "total": 31,
    "page": 1,
    "per_page": 20
  }
}

Manual match runs

You can also trigger matching manually:

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/match-runs" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "dry_run": false,
   "date_range": {
     "from": "2024-01-15",
     "to": "2024-01-20"
   }
 }'

Set dry_run: true to preview results without confirming matches.

Advanced context configuration

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Multi-Currency Payment Reconciliation",
   "description": "Payment gateway transactions across multiple currencies",
   "type": "ONE_TO_MANY",
   "tenant_id": "tenant_001",
   "settings": {
     "date_tolerance_days": 5,
     "auto_confirm_threshold": 95,
     "review_threshold": 70,
     "allow_partial_match": true,
     "require_currency_match": false,
     "enable_many_to_many": false,
     "amount_tolerance": {
       "type": "percentage",
       "value": 1.0
     },
     "fx_settings": {
       "enabled": true,
       "rate_source": "daily_close",
       "tolerance_percent": 2.0
     }
   },
   "schedule": {
     "frequency": "daily",
     "time": "06:00",
     "timezone": "UTC"
   },
   "notifications": {
     "on_complete": [
       "[email protected]"
     ],
     "on_exceptions": [
       "[email protected]"
     ]
   }
 }'

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 source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "description": "Daily bank statement feed from Chase",
   "direction": "EXTERNAL",
   "settings": {
     "currency": "USD",
     "timezone": "America/New_York"
   }
 }'

Add an internal source

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Main Ledger - GL 1000",
   "type": "LEDGER",
   "description": "General ledger cash account from ERP",
   "direction": "INTERNAL",
   "settings": {
     "currency": "USD",
     "timezone": "America/New_York"
   }
 }'

Source types

Type	Description	Typical direction
`BANK`	Bank statements	External
`LEDGER`	General ledger accounts	Internal
`PAYMENT_GATEWAY`	Payment processor transactions	External
`ERP`	Enterprise systems	Internal
`CUSTOM`	Custom integrations	Varies

Source direction

Source direction indicates data ownership and origin.

Direction	Description	Examples
`INTERNAL`	Originates from internal systems	Ledger, ERP
`EXTERNAL`	Provided by third parties	Banks, gateways

Direction is used for:

Exception classification and routing
Audit attribution
Variance ownership analysis

Source configuration options

Basic settings

{
  "settings": {
    "currency": "USD",
    "timezone": "America/New_York",
    "date_format": "YYYY-MM-DD",
    "amount_sign_convention": "NATURAL"
  }
}

Amount sign conventions

Convention	Description	Example
`NATURAL`	Positive = credit, negative = debit	+100 / -50
`ABSOLUTE_WITH_TYPE`	Always positive, direction defined separately	100 credit / 50 debit
`INVERTED`	Positive = debit, negative = credit	Inverted signs

Regulatory flags

{
  "settings": {
    "regulatory": true,
    "regulatory_type": "SOX",
    "retention_years": 7
  }
}

When enabled, regulatory sources:

Elevate exceptions to critical severity
Require justification for resolutions
Enforce extended audit retention

Managing contexts

Update context settings

cURL

curl -X PATCH "https://api.matcher.example.com/v1/contexts/ctx_abc123" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "settings": {
     "auto_confirm_threshold": 85,
     "date_tolerance_days": 5
   }
 }'

Deactivate a context

curl -X POST "https://api.matcher.example.com/v1/contexts/ctx_abc123/deactivate" \
 -H "Authorization: Bearer $TOKEN"

Deactivating a context:

Stops scheduled executions
Preserves historical data
Allows future reactivation

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

​What is a reconciliation context?

​Context types

​One-to-one (1:1)

​One-to-many (1:n)

​Many-to-many (n:m)

​Creating a context

​Basic context creation

​Request

​Response

​Context settings

​Automatic match scheduling

​Schedule configuration

​Schedule frequencies

​Custom schedules

​Match run behavior

​Viewing match run history

​Manual match runs

​Advanced context configuration

​What is a source?

​Adding sources to a context

​Create a source

​Add an internal source

​Source types

​Source direction

​Source configuration options

​Basic settings

​Amount sign conventions

​Regulatory flags

​Managing contexts

​Update context settings

​Deactivate 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 context

Basic context creation

Request

Response

Context settings

Automatic match scheduling

Schedule configuration

Schedule frequencies

Custom schedules

Match run behavior

Viewing match run history

Manual match runs

Advanced context configuration

What is a source?

Adding sources to a context

Create a source

Add an internal source

Source types

Source direction

Source configuration options

Basic settings

Amount sign conventions

Regulatory flags

Managing contexts

Update context settings

Deactivate a context

Context lifecycle

Best practices

Next steps