Match rules

Author exact, tolerance, date-lag, and fuzzy rules in Matcher — set priorities, tolerances, and reference matching to control how transactions pair up.

Match rules are where you set your reconciliation policy — how strict or forgiving Matcher should be when deciding 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 free-text references 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 keeps higher-priority matches from being reused while allowing progressively looser rules to process the remaining transactions.

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.

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: Free-text memos or truncated references where the reference 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

matchAmount · Boolean · default: "true"

Require exact amount match

matchCurrency · Boolean · default: "true"

Require exact currency match

matchDate · Boolean · default: "true"

Require exact date match

matchReference · Boolean · default: "true"

Require exact reference match

datePrecision · String · default: "DAY"

Date comparison precision: DAY or TIMESTAMP

caseInsensitive · Boolean · default: "true"

Case-insensitive reference comparison

referenceMustSet · Boolean · default: "false"

Require reference to be present on both sides

matchBaseAmount · Boolean · default: "false"

Match on base (converted) amount instead of original

matchBaseCurrency · Boolean · default: "false"

Match on base currency instead of original

matchScore · Integer · default: "100"

Accepted and validated, but reserved/inert — does not change the calculated confidence score (see note below)

matchBaseScore · Integer · default: "90"

Accepted and validated, but reserved/inert — does not change the calculated confidence score (see note below)

matchScore and matchBaseScore are currently 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). These fields are reserved for future use and 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

percentTolerance · Decimal

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

absTolerance · 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.

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 · default: "MAX"

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

matchCurrency · Boolean · default: "true"

Require currency match

matchReference · Boolean · default: "true"

Require reference match

caseInsensitive · Boolean · default: "true"

Case-insensitive reference comparison

referenceMustSet · Boolean · default: "false"

Require reference to be present on both sides

matchBaseAmount · Boolean · default: "false"

Match on base (converted) amount

matchBaseCurrency · Boolean · default: "false"

Match on base currency

matchScore · Integer · default: "85"

Accepted and validated, but reserved/inert — does not change the calculated confidence score

matchBaseScore · Integer · default: "80"

Accepted and validated, but reserved/inert — 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

minSimilarity · Decimal · default: "0.80"

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

matchAmount · Boolean · default: "true"

When true, require an exact amount match

matchCurrency · Boolean · default: "true"

When true, require an exact currency match

matchDate · Boolean · default: "true"

When true, require an exact date match

datePrecision · String · default: "DAY"

Date comparison precision: DAY or TIMESTAMP

referenceMustSet · Boolean · default: "true"

Require a non-empty reference on both sides

matchScore · Integer · default: "70"

Accepted and defaulted to 70, but reserved/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

maxDays · Integer

Maximum number of days difference allowed

minDays · Integer · default: "0"

Minimum number of days difference required

inclusive · Boolean · default: "true"

Whether the boundary days are inclusive

direction · String · default: "ABS"

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

feeTolerance · Decimal · default: "0"

Allowed amount difference to account for fees

matchScore · Integer · default: "80"

Accepted and validated, but reserved/inert — 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

matchCurrency · 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
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/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 returns potential matches. It does not create exceptions, but Matcher completes and persists the MatchRun with statistics and emits its completion event.

Managing rules

---

List rules

cURL

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.

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

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"

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.