Match rules

Match rules are where you set your reconciliation policy. The policy sets how strict or forgiving Matcher is when it decides two transactions are the same. Tight rules mean more manual review but fewer false matches. Looser rules automate more but need careful oversight. You can enforce exact matches, allow controlled variance, tolerate timing differences, or compare external IDs by similarity.

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.
Each rule creates all matches it can from transactions not already used by higher-priority rules.
After every rule runs, transactions that remain unmatched become exceptions.

This approach stops any rule from reusing a higher-priority match. Progressively looser rules process the transactions that remain.

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. DATE_LAG always proposes a match for review and never auto-confirms, whatever its score.

Best for: Posting delays between systems.

Fuzzy

Replaces exact reference equality with normalized string-similarity scoring. Amount, currency, and date gates require exact equality by default, but matchAmount, matchCurrency, and matchDate independently control whether each gate applies. FUZZY always proposes a match for review and never auto-confirms.

Best for: Truncated or reformatted external IDs, where the ID varies but the enabled financial gates still align.

Creating match rules

Exact rule

cURL

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

Boolean

default:"true"

Require exact amount match

Boolean

default:"true"

Require exact currency match

Boolean

default:"true"

Require exact date match

Boolean

default:"true"

Require exact reference match

String

default:"DAY"

Date comparison precision: DAY or TIMESTAMP

Boolean

default:"true"

Case-insensitive reference comparison

Boolean

default:"false"

Require reference to be present on both sides

Boolean

default:"false"

Require equal base (converted) amounts, in addition to the matchAmount check

Boolean

default:"false"

Require the same base currency, in addition to the matchCurrency check

Integer

default:"100"

Accepted and validated, but inert. It does not change the calculated confidence score (see note below)

Integer

default:"90"

Accepted and validated, but inert. It does not change the calculated confidence score (see note below)

matchScore and matchBaseScore are inert. They are accepted and validated in the rule config, but the scoring engine ignores them: confidence is always computed from the fixed internal component weights (amount 40, currency 30, date 20, reference 10). Setting them does not alter the confidence score or auto-confirm behavior. See Confidence scoring.

The response echoes the persisted rule with its assigned id and timestamps.

API Reference: Create match rule

Tolerance rule

cURL

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

Decimal

Percentage threshold applied to percentageBase (0.005 = 0.5%). Defaults to 0. Matcher compares this threshold with absTolerance and uses the larger one

Decimal

Absolute amount threshold. Defaults to 0. Matcher compares it with the percentage threshold and uses the larger one

Both thresholds default to zero, so you must configure any permitted amount variance explicitly.

Integer

Number of days allowed between transaction dates

Integer

Decimal places for rounding

String

Rounding strategy: HALF_UP, BANKERS, FLOOR, CEIL, or TRUNCATE

String

default:"MAX"

Base for percentage calculation: MAX, MIN, AVERAGE, LEFT, or RIGHT

Boolean

default:"true"

Require currency match

Boolean

default:"true"

Require reference match

Boolean

default:"true"

Case-insensitive reference comparison

Boolean

default:"false"

Require reference to be present on both sides

Boolean

default:"false"

Match on base (converted) amount

Boolean

default:"false"

Match on base currency

Integer

default:"85"

Accepted and validated, but inert. It does not change the calculated confidence score

Integer

default:"80"

Accepted and validated, but inert. It does not change the calculated confidence score

Example:

Transaction A: $1,000.00
Transaction B: $1,005.00
Amount difference: $5.00
Percentage threshold: $1,005.00 × 0.5% =$ 5.025 (percentageBase: MAX)
Absolute threshold: $0.50
Effective threshold: MAX($5.025, $0.50) = $5.025 → Matches

Fuzzy rule

cURL

curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "FUZZY",
   "priority": 4,
   "config": {
     "minSimilarity": 0.85,
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "datePrecision": "DAY",
     "referenceMustSet": true,
     "matchScore": 70
   }
 }'

Config reference

Decimal

default:"0.80"

Minimum normalized reference similarity (0–1) required to gate as a match

Boolean

default:"true"

When true, require an exact amount match

Boolean

default:"true"

When true, require an exact currency match

Boolean

default:"true"

When true, require an exact date match

String

default:"DAY"

Date comparison precision: DAY or TIMESTAMP

Boolean

default:"true"

Require a non-empty reference on both sides

Integer

default:"70"

Accepted and defaulted to 70, but inert. It does not cap or change calculated confidence or auto-confirm behavior

FUZZY replaces reference equality with similarity. By default, it also requires exact amount, currency, and date matches. Disable each gate independently with matchAmount, matchCurrency, or matchDate. FUZZY always proposes matches for human review and never auto-confirms them.

Date lag rule

cURL

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

Integer

Maximum number of days difference allowed

Integer

default:"0"

Minimum number of days difference required

Boolean

default:"true"

Whether the boundary days are inclusive

String

default:"ABS"

How to measure the lag: ABS (absolute), LEFT_BEFORE_RIGHT, or RIGHT_BEFORE_LEFT

Decimal

default:"0"

Allowed amount difference to account for fees

Integer

default:"80"

Accepted and validated, but inert. It does not change the calculated confidence score. Note that DATE_LAG rules always score the reference component as 0, capping the maximum score at 90

Boolean

default:"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
`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. Each priority is an integer from 1 to 1000 and is unique within the context. Matcher refuses a priority that another rule already uses with 409 (MTCH-0102).

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/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"
   ]
 }'

Matcher then renumbers every rule in the context from 1, in the new order. Rules that you leave out of the list follow the listed rules, in their previous order.

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 returns only the runId and status. It does not create exceptions, but Matcher completes and persists the MatchRun with statistics and emits its completion event. Read the statistics with GET /v1/matching/runs/{runId}.

Managing rules

List rules

cURL

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

Response

Each item is the full rule, in the same shape as the create response, including config.

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

config replaces the whole stored configuration. Matcher does not merge it with the previous one, so a key that you omit returns to its default.

API Reference: Update match rule

Delete a rule

cURL

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

Matcher refuses the delete with 409 (MTCH-0118) while a confirmed match group that this rule created still has an exception attached.

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.

Dry-run every change

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

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.

Overview

Guides

Console

MCP Server

Operations

How rules work

Rule types

Exact

Tolerance

Date lag

Fuzzy

Creating match rules

Exact rule

Config reference

Tolerance rule

Config reference

Fuzzy 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

​Fuzzy

​Creating match rules

​Exact rule

​Config reference

​Tolerance rule

​Config reference

​Fuzzy 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

Fuzzy

Creating match rules

Exact rule

Config reference

Tolerance rule

Config reference

Fuzzy 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