> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Contexts and sources

> Learn how contexts define reconciliation scope and sources connect the systems that feed transaction data into Matcher.

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

```bash cURL theme={null}
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

| 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`)         |
| `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

```json theme={null}
{
  "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"
}
```

<Tip>API Reference: [Create context](/en/reference/matcher/create-context)</Tip>

## 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:

```bash cURL theme={null}
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

```json theme={null}
{
  "runId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PROCESSING"
}
```

<Tip>API Reference: [Run match](/en/reference/matcher/run-match)</Tip>

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

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

#### Response

```json theme={null}
{
  "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
}
```

<Tip>API Reference: [List match runs](/en/reference/matcher/list-match-runs)</Tip>

### 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

```bash cURL theme={null}
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"
 }'
```

#### Response

```json theme={null}
{
  "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"
}
```

<Tip>API Reference: [Create source](/en/reference/matcher/create-source)</Tip>

### Create a ledger source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/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:

```bash cURL theme={null}
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",
   "config": {
     "currency": "USD",
     "provider": "stripe"
   }
 }'
```

| Field    | Type   | Description                                           |
| -------- | ------ | ----------------------------------------------------- |
| `name`   | String | Descriptive name for the source                       |
| `type`   | String | Source type: `LEDGER`, `BANK`, `GATEWAY`, or `CUSTOM` |
| `config` | Object | Flexible key-value pairs for integration metadata     |

## Managing contexts

***

### Update a context

```bash cURL theme={null}
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"
 }'
```

<Tip>API Reference: [Update context](/en/reference/matcher/update-context)</Tip>

### Pause a context

To temporarily stop a context from being used in reconciliation runs, update its status to `PAUSED`:

```bash cURL theme={null}
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`

### Delete a context

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

<Tip>API Reference: [Delete context](/en/reference/matcher/delete-context)</Tip>

### 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.

```bash cURL theme={null}
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,
   "includeFeeSchedules": true
 }'
```

#### Response

```json theme={null}
{
  "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
}
```

<Tip>API Reference: [Clone context](/en/reference/matcher/clone-context)</Tip>

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.

<Frame caption="Lifecycle of a Matcher context">
  <img src="https://mintcdn.com/lerian-49cb71fc/UsUgoha8b-OkDZPH/images/en/docs/matcher-context-lifecycle.jpg?fit=max&auto=format&n=UsUgoha8b-OkDZPH&q=85&s=05bcbc86a09e9fa5d7af8e73d567592d" alt="Matcher Context Lifecycle" width="1267" height="1232" data-path="images/en/docs/matcher-context-lifecycle.jpg" />
</Frame>

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

## Best practices

***

<AccordionGroup>
  <Accordion title="Use descriptive names">
    Use explicit names that reflect accounts, systems, and purpose.
  </Accordion>

  <Accordion title="Start with conservative thresholds">
    Favor accuracy over automation initially. Adjust thresholds based on observed results.
  </Accordion>

  <Accordion title="Separate concerns">
    Use multiple contexts instead of a single broad reconciliation.
  </Accordion>

  <Accordion title="Flag regulatory sources">
    Always mark sources with compliance requirements.
  </Accordion>

  <Accordion title="Align timezones">
    Ensure source timezones reflect the original data feed.
  </Accordion>

  <Accordion title="Document sign conventions">
    Explicitly define debit and credit semantics for each source.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Field mapping" icon="arrows-left-right" href="/en/matcher/configuration/matcher-field-mapping">
    Define how source fields map to Matcher's schema.
  </Card>

  <Card title="Match rules" icon="scale-balanced" href="/en/matcher/configuration/matcher-match-rules">
    Configure the rules that drive reconciliation.
  </Card>
</CardGroup>