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

# Match rules

> Configure exact, tolerance, and date-lag rules to control how Matcher compares transactions across sources.

Match rules define how Matcher compares transactions across sources. You can enforce strict matches, allow controlled variance, or model more advanced logic with composite conditions.

## How rules work

***

When a matching run starts, Matcher evaluates rules in priority order.

* Rules are evaluated from the lowest priority number to the highest.
* The first rule that produces a match determines the outcome.
* If no rule matches, the transaction becomes an exception.

This approach ensures deterministic matching while allowing progressively looser rules as fallbacks.

## Rule types

***

### Exact

Requires a strict match on configured fields.

* **Best for**: Deterministic matches where values should align 1:1.

### Tolerance

Allows controlled variance in amount matching.

* **Best for**: Known variance patterns such as fees, rounding, or FX differences.

### Date lag

Allows date differences between transactions.

* **Best for**: Posting delays between systems.

## Creating match rules

***

### 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,
     "datePrecision": "DAY",
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 100,
     "matchBaseScore": 90
   }
 }'
```

#### Config reference

| Field               | Type    | Default | Description                                                |
| ------------------- | ------- | ------- | ---------------------------------------------------------- |
| `matchAmount`       | Boolean | true    | Require exact amount match                                 |
| `matchCurrency`     | Boolean | true    | Require exact currency match                               |
| `matchDate`         | Boolean | true    | Require exact date match                                   |
| `matchReference`    | Boolean | true    | Require exact reference match                              |
| `datePrecision`     | String  | `"DAY"` | Date comparison precision: `DAY` or `TIMESTAMP`            |
| `caseInsensitive`   | Boolean | true    | Case-insensitive reference comparison                      |
| `referenceMustSet`  | Boolean | false   | Require reference to be present on both sides              |
| `matchBaseAmount`   | Boolean | false   | Match on base (converted) amount instead of original       |
| `matchBaseCurrency` | Boolean | false   | Match on base currency instead of original                 |
| `matchScore`        | Integer | 100     | Confidence score assigned when rule matches                |
| `matchBaseScore`    | Integer | 90      | Confidence score assigned when rule matches on base amount |

#### Response

```json theme={null}
{
  "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
  "contextId": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "type": "EXACT",
  "priority": 1,
  "config": {
    "matchAmount": true,
    "matchCurrency": true,
    "matchDate": true,
    "matchReference": true,
    "datePrecision": "DAY",
    "caseInsensitive": true,
    "referenceMustSet": false,
    "matchBaseAmount": false,
    "matchBaseCurrency": false,
    "matchScore": 100,
    "matchBaseScore": 90
  },
  "createdAt": "2026-02-02T16:40:00Z",
  "updatedAt": "2026-02-02T16:40:00Z"
}
```

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

### Tolerance 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": "TOLERANCE",
   "priority": 2,
   "config": {
     "percentTolerance": 0.005,
     "absTolerance": 0.50,
     "dateWindowDays": 3,
     "roundingScale": 2,
     "roundingMode": "HALF_UP",
     "percentageBase": "MAX",
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true,
     "referenceMustSet": false,
     "matchBaseAmount": false,
     "matchBaseCurrency": false,
     "matchScore": 85,
     "matchBaseScore": 80
   }
 }'
```

#### Config reference

| Field               | Type    | Default | Description                                                                  |
| ------------------- | ------- | ------- | ---------------------------------------------------------------------------- |
| `percentTolerance`  | Decimal | 0.005   | Maximum percentage variance allowed (0.005 = 0.5%)                           |
| `absTolerance`      | Decimal | 0.50    | Maximum absolute amount variance allowed                                     |
| `dateWindowDays`    | Integer | —       | Number of days allowed between transaction dates                             |
| `roundingScale`     | Integer | —       | Decimal places for rounding                                                  |
| `roundingMode`      | String  | —       | Rounding strategy: `HALF_UP`, `BANKERS`, `FLOOR`, `CEIL`, or `TRUNCATE`      |
| `percentageBase`    | String  | —       | Base for percentage calculation: `MAX`, `MIN`, `AVERAGE`, `LEFT`, or `RIGHT` |
| `matchCurrency`     | Boolean | true    | Require currency match                                                       |
| `matchReference`    | Boolean | true    | Require reference match                                                      |
| `caseInsensitive`   | Boolean | true    | Case-insensitive reference comparison                                        |
| `referenceMustSet`  | Boolean | false   | Require reference to be present on both sides                                |
| `matchBaseAmount`   | Boolean | false   | Match on base (converted) amount                                             |
| `matchBaseCurrency` | Boolean | false   | Match on base currency                                                       |
| `matchScore`        | Integer | 85      | Confidence score when rule matches                                           |
| `matchBaseScore`    | Integer | 80      | Confidence score when rule matches on base amount                            |

**Example:**

* Transaction A: \$1,000.00
* Transaction B: \$1,005.00
* Variance: 0.5% → **Matches** (within 0.5% tolerance and \$0.50 absolute tolerance)

### Date lag 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": "DATE_LAG",
   "priority": 3,
   "config": {
     "maxDays": 3,
     "minDays": 0,
     "inclusive": true,
     "direction": "ABS",
     "feeTolerance": 0,
     "matchScore": 80,
     "matchCurrency": true
   }
 }'
```

#### Config reference

| Field           | Type    | Default | Description                                                                           |
| --------------- | ------- | ------- | ------------------------------------------------------------------------------------- |
| `maxDays`       | Integer | —       | Maximum number of days difference allowed                                             |
| `minDays`       | Integer | 0       | Minimum number of days difference required                                            |
| `inclusive`     | Boolean | true    | Whether the boundary days are inclusive                                               |
| `direction`     | String  | `"ABS"` | How to measure the lag: `ABS` (absolute), `LEFT_BEFORE_RIGHT`, or `RIGHT_BEFORE_LEFT` |
| `feeTolerance`  | Decimal | 0       | Allowed amount difference to account for fees                                         |
| `matchScore`    | Integer | 80      | Confidence score when rule matches                                                    |
| `matchCurrency` | Boolean | true    | Require currency match                                                                |

### Allocation settings (all rule types)

All rule types accept additional allocation settings for split and aggregate matching:

| Field                      | Type    | Description                                              |
| -------------------------- | ------- | -------------------------------------------------------- |
| `allowPartial`             | Boolean | Allow partial allocation of transaction amounts          |
| `allocationDirection`      | String  | Allocation order: `LEFT_TO_RIGHT` or `RIGHT_TO_LEFT`     |
| `allocationToleranceMode`  | String  | How tolerance is measured: `ABS` (absolute) or `PERCENT` |
| `allocationToleranceValue` | Decimal | Tolerance threshold for allocation                       |
| `allocationUseBaseAmount`  | Boolean | Use base (converted) amount for allocation               |

## Rule priority

***

Rules are evaluated by priority. Lower numbers run first.

### Priority strategy

| Priority | Rule type | Use case                         |
| -------- | --------- | -------------------------------- |
| 1–10     | EXACT     | Deterministic matches            |
| 11–50    | TOLERANCE | Small, expected variance         |
| 51–100   | DATE\_LAG | Date differences between systems |

### Reorder rules

You can reorder rules by providing the rule IDs in the desired order:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules/reorder" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "ruleIds": [
     "550e8400-e29b-41d4-a716-446655440001",
     "550e8400-e29b-41d4-a716-446655440002",
     "550e8400-e29b-41d4-a716-446655440000"
   ]
 }'
```

<Tip>API Reference: [Reorder match rules](/en/reference/matcher/reorder-match-rules)</Tip>

## Testing rules

***

Test rules in dry-run mode before committing 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": "DRY_RUN"
 }'
```

Dry run mode evaluates all rules and shows potential matches without persisting results.

## Managing rules

***

### List rules

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

#### Response

The list endpoint returns a summary view of rules. To see the full configuration details for a specific rule, use the individual rule endpoint or the create response which includes the complete `config` object.

```json theme={null}
{
  "items": [
    {
      "id": "019c96a0-2b20-7123-9a1b-2c3d4e5f6a7b",
      "contextId": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
      "type": "EXACT",
      "priority": 1,
      "config": {
        "matchAmount": true,
        "matchCurrency": true,
        "matchDate": true,
        "matchReference": true,
        "datePrecision": "DAY",
        "matchScore": 100,
        "matchBaseScore": 90
      },
      "createdAt": "2026-02-02T16:40:00Z",
      "updatedAt": "2026-02-02T16:40:00Z"
    }
  ],
  "limit": 20,
  "hasMore": false
}
```

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

### Update a rule

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "priority": 5,
   "type": "TOLERANCE",
   "config": {
     "percentTolerance": 0.02,
     "absTolerance": 10.0
   }
 }'
```

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

### Delete a rule

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

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

## Best practices

***

<AccordionGroup>
  <Accordion title="Start strict, then loosen">
    Lead with exact rules. Add tolerance rules only for the variance you can justify and explain.
  </Accordion>

  <Accordion title="Leave room in priorities">
    Use gaps (1, 10, 20, 50) so you can insert rules without renumbering your entire set.
  </Accordion>

  <Accordion title="Dry-run every change">
    Treat rule updates as production changes. Validate match rates and exception volume before committing.
  </Accordion>

  <Accordion title="Write descriptions that explain intent">
    A rule should document the variance it covers and the risk it introduces.
  </Accordion>

  <Accordion title="Review rule output over time">
    If a rule never matches, it may be unnecessary. If it matches too often, it may be too broad.
  </Accordion>

  <Accordion title="Keep loose rules at low priority">
    High tolerance increases false positives. Use it as a fallback and review results carefully.
  </Accordion>
</AccordionGroup>

## Next steps

***

<CardGroup cols={2}>
  <Card title="Exception routing" icon="route" href="/en/matcher/configuration/matcher-exception-routing">
    Configure classification, assignment, and escalation for unmatched transactions.
  </Card>

  <Card title="Confidence scoring" icon="chart-simple" href="/en/matcher/reference/matcher-confidence-scoring">
    Understand how scores are calculated and how thresholds impact automation.
  </Card>
</CardGroup>