Match rules

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

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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

{
  "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"
}

API Reference: Create match rule

Tolerance rule

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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:

cURL

curl -X POST "https://api.matcher.example.com/v1/config/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"
   ]
 }'

API Reference: Reorder match rules

Testing rules

Test rules in dry-run mode before committing matches.

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

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

Managing rules

List rules

cURL

curl -X GET "https://api.matcher.example.com/v1/config/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.

{
  "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
}

API Reference: List match rules

Update a rule

cURL

curl -X PATCH "https://api.matcher.example.com/v1/config/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
   }
 }'

API Reference: Update match rule

Delete a rule

cURL

curl -X DELETE "https://api.matcher.example.com/v1/config/contexts/{contextId}/rules/{ruleId}" \
 -H "Authorization: Bearer $TOKEN"

API Reference: Delete match rule

Best practices

Start strict, then loosen

Lead with exact rules. Add tolerance rules only for the variance you can justify and explain.

Leave room in priorities

Use gaps (1, 10, 20, 50) so you can insert rules without renumbering your entire set.

Dry-run every change

Treat rule updates as production changes. Validate match rates and exception volume before committing.

Write descriptions that explain intent

A rule should document the variance it covers and the risk it introduces.

Review rule output over time

If a rule never matches, it may be unnecessary. If it matches too often, it may be too broad.

Keep loose rules at low priority

High tolerance increases false positives. Use it as a fallback and review results carefully.

Next steps

Exception routing

Configure classification, assignment, and escalation for unmatched transactions.

Confidence scoring

Understand how scores are calculated and how thresholds impact automation.

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

How rules work

Rule types

Exact

Tolerance

Date lag

Creating match rules

Exact rule

Config reference

Response

Tolerance rule

Config reference

Date lag rule

Config reference

Allocation settings (all rule types)

Rule priority

Priority strategy

Reorder rules

Testing rules

Managing rules

List rules

Response

Update a rule

Delete a rule

Best practices

Next steps

Exception routing

Confidence scoring

Introduction

Getting started

Configuration

Daily reconciliation

Integrations

Reference

​How rules work

​Rule types

​Exact

​Tolerance

​Date lag

​Creating match rules

​Exact rule

​Config reference

​Response

​Tolerance rule

​Config reference

​Date lag rule

​Config reference

​Allocation settings (all rule types)

​Rule priority

​Priority strategy

​Reorder rules

​Testing rules

​Managing rules

​List rules

​Response

​Update a rule

​Delete a rule

​Best practices

​Next steps

Exception routing

Confidence scoring

How rules work

Rule types

Exact

Tolerance

Date lag

Creating match rules

Exact rule

Config reference

Response

Tolerance rule

Config reference

Date lag rule

Config reference

Allocation settings (all rule types)

Rule priority

Priority strategy

Reorder rules

Testing rules

Managing rules

List rules

Response

Update a rule

Delete a rule

Best practices

Next steps