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

# Matcher API quick start

<Tip>
  **This guide is intended for developers.** If you're looking for a business-level overview of what Matcher does and how it helps your team, see [What is Matcher?](/en/matcher/what-is-matcher).
</Tip>

Get Matcher running in minutes. This guide walks you through the complete journey, from creating your first reconciliation context to reviewing matched transactions.

## Before you begin

***

You need:

* A running Matcher instance
* A valid JWT token for authentication
* Two transaction files to reconcile (CSV, JSON, or XML)

All examples use `cURL`. Replace `$TOKEN` with your JWT token and `https://api.matcher.example.com` with your Matcher URL.

## Step 1: Create a reconciliation context

***

A context defines the scope of your reconciliation: what you are comparing and how.

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

```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",
   "type": "1:1",
   "interval": "daily"
 }'
```

The `type` field defines how transactions are paired:

| Type  | Description                                       |
| ----- | ------------------------------------------------- |
| `1:1` | Each transaction matches exactly one counterpart  |
| `1:N` | One transaction can match multiple counterparts   |
| `N:M` | Multiple transactions can match across both sides |

Save the `id` from the response. You will use it in every subsequent step.

```json theme={null}
{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
```

<Info>
  The context starts in DRAFT status. It moves to ACTIVE when you are ready to run reconciliation.
</Info>

## Step 2: Add data sources

***

Every context needs at least two sources: the systems whose transactions you want to compare.

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

### 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"
 }'
```

### 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": "General Ledger - GL 1000",
   "type": "LEDGER"
 }'
```

Save both source `id` values.

### Source types

| Type      | Use case                     |
| --------- | ---------------------------- |
| `BANK`    | Bank statements              |
| `LEDGER`  | General ledger / ERP exports |
| `GATEWAY` | Payment processor data       |
| `CUSTOM`  | Any other data source        |

## Step 3: Map source fields

***

Your source files probably use different column names than Matcher expects. Field maps translate them into Matcher's standard schema.

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

### Map the bank source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "Transaction ID": "transaction_id",
     "Amount": "amount",
     "Currency": "currency",
     "Post Date": "date",
     "Description": "reference"
   }
 }'
```

### Map the ledger source

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "entry_id": "transaction_id",
     "debit_credit_amount": "amount",
     "currency_code": "currency",
     "posting_date": "date",
     "memo": "reference"
   }
 }'
```

### Required fields

Every transaction must have these fields after mapping:

| Field            | Type    | Description                         |
| ---------------- | ------- | ----------------------------------- |
| `transaction_id` | String  | Unique identifier within the source |
| `amount`         | Decimal | Transaction amount                  |
| `currency`       | String  | ISO 4217 currency code (e.g. USD)   |
| `date`           | Date    | Transaction date (YYYY-MM-DD)       |

**Optional but recommended:** `reference` (external reference or description).

## Step 4: Create match rules

***

Rules define how Matcher compares transactions. Start with an exact rule, which is the most precise.

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

### Create an exact rule

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'
```

### Add a tolerance rule as fallback

Catch small differences like bank fees or rounding:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 20,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'
```

<Tip>
  Matcher evaluates rules by priority (lowest number first). The exact rule runs first. Only unmatched transactions fall through to the tolerance rule.
</Tip>

### Rule types

| Type        | When to use                 | Priority range |
| ----------- | --------------------------- | -------------- |
| `EXACT`     | Values should match exactly | 1-10           |
| `TOLERANCE` | Small, expected differences | 11-50          |
| `DATE_LAG`  | Date delays between systems | 51-100         |

## Step 5: Activate the context

***

Move the context from DRAFT to ACTIVE:

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

```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": "ACTIVE"
 }'
```

## Step 6: Upload transaction files

***

Upload one file per source. Matcher accepts CSV, JSON, and XML formats via multipart form upload.

<Tip>
  * API reference: [Upload transaction file](/en/reference/matcher/upload-transaction-file)
  * [List ingestion jobs](/en/reference/matcher/list-ingestion-jobs)
</Tip>

### Upload bank transactions

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@bank_transactions.csv" \
 -F "format=csv"
```

### Upload ledger transactions

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "file=@ledger_entries.csv" \
 -F "format=csv"
```

Each upload creates an ingestion job. Check the job status:

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

Wait for both jobs to reach `COMPLETED` status before running the match.

## Step 7: Run matching

***

Start with a dry run to preview results without persisting:

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

```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": "DRY_RUN"
 }'
```

Both responses include a `runId`. Save it for Step 8.

Review the dry run results. When satisfied, run with COMMIT to persist matches:

```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"
 }'
```

## Step 8: Review results

***

<Tip>
  * API reference: [List match run groups](/en/reference/matcher/list-match-run-groups)
  * [Unmatch group](/en/reference/matcher/unmatch-group)
</Tip>

### View match groups

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

Each match group contains paired transactions and a confidence score (0-100):

| Score    | What happens                           |
| -------- | -------------------------------------- |
| 90-100   | Auto-confirmed, no action needed       |
| 60-89    | Needs manual review                    |
| Below 60 | No match created, becomes an exception |

### Undo an incorrect match

Use the unmatch endpoint to reject a match group and return transactions to the unmatched pool:

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Transactions belong to different records"
 }'
```

Rejected transactions return to the unmatched pool for the next run.

## Step 9: Handle exceptions

***

Exceptions are transactions that could not be matched automatically. Matcher classifies each exception by severity:

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

| Severity   | Criteria                         | SLA      |
| ---------- | -------------------------------- | -------- |
| `CRITICAL` | Amount >= 100,000 or age >= 120h | 24 hours |
| `HIGH`     | Amount >= 10,000 or age >= 72h   | 72 hours |
| `MEDIUM`   | Amount >= 1,000 or age >= 24h    | 5 days   |
| `LOW`      | All others                       | 7 days   |

### List exceptions

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

Resolve exceptions by force matching, creating adjustments, or dispatching to external systems like JIRA.

## Next steps

***

<CardGroup cols={2}>
  <Card title="Contexts and sources" icon="database" href="/en/matcher/configuration/matcher-contexts-and-sources">
    Full guide to context and source configuration.
  </Card>

  <Card title="Match rules" icon="scale-balanced" href="/en/matcher/configuration/matcher-match-rules">
    All rule types and config options in detail.
  </Card>

  <Card title="Confidence scoring" icon="chart-simple" href="/en/matcher/reference/matcher-confidence-scoring">
    How scores are calculated and what they mean.
  </Card>

  <Card title="Resolving exceptions" icon="triangle-exclamation" href="/en/matcher/daily-reconciliation/matcher-resolving-exceptions">
    Handle unmatched transactions.
  </Card>
</CardGroup>