Skip to main content
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

FieldTypeDefaultDescription
matchAmountBooleantrueRequire exact amount match
matchCurrencyBooleantrueRequire exact currency match
matchDateBooleantrueRequire exact date match
matchReferenceBooleantrueRequire exact reference match
datePrecisionString"DAY"Date comparison precision: DAY or TIMESTAMP
caseInsensitiveBooleantrueCase-insensitive reference comparison
referenceMustSetBooleanfalseRequire reference to be present on both sides
matchBaseAmountBooleanfalseMatch on base (converted) amount instead of original
matchBaseCurrencyBooleanfalseMatch on base currency instead of original
matchScoreInteger100Confidence score assigned when rule matches
matchBaseScoreInteger90Confidence 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

FieldTypeDefaultDescription
percentToleranceDecimal0.005Maximum percentage variance allowed (0.005 = 0.5%)
absToleranceDecimal0.50Maximum absolute amount variance allowed
dateWindowDaysIntegerNumber of days allowed between transaction dates
roundingScaleIntegerDecimal places for rounding
roundingModeStringRounding strategy: HALF_UP, BANKERS, FLOOR, CEIL, or TRUNCATE
percentageBaseStringBase for percentage calculation: MAX, MIN, AVERAGE, LEFT, or RIGHT
matchCurrencyBooleantrueRequire currency match
matchReferenceBooleantrueRequire reference match
caseInsensitiveBooleantrueCase-insensitive reference comparison
referenceMustSetBooleanfalseRequire reference to be present on both sides
matchBaseAmountBooleanfalseMatch on base (converted) amount
matchBaseCurrencyBooleanfalseMatch on base currency
matchScoreInteger85Confidence score when rule matches
matchBaseScoreInteger80Confidence 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

FieldTypeDefaultDescription
maxDaysIntegerMaximum number of days difference allowed
minDaysInteger0Minimum number of days difference required
inclusiveBooleantrueWhether the boundary days are inclusive
directionString"ABS"How to measure the lag: ABS (absolute), LEFT_BEFORE_RIGHT, or RIGHT_BEFORE_LEFT
feeToleranceDecimal0Allowed amount difference to account for fees
matchScoreInteger80Confidence score when rule matches
matchCurrencyBooleantrueRequire currency match

Allocation settings (all rule types)

All rule types accept additional allocation settings for split and aggregate matching:
FieldTypeDescription
allowPartialBooleanAllow partial allocation of transaction amounts
allocationDirectionStringAllocation order: LEFT_TO_RIGHT or RIGHT_TO_LEFT
allocationToleranceModeStringHow tolerance is measured: ABS (absolute) or PERCENT
allocationToleranceValueDecimalTolerance threshold for allocation
allocationUseBaseAmountBooleanUse base (converted) amount for allocation

Rule priority


Rules are evaluated by priority. Lower numbers run first.

Priority strategy

PriorityRule typeUse case
1–10EXACTDeterministic matches
11–50TOLERANCESmall, expected variance
51–100DATE_LAGDate 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


Lead with exact rules. Add tolerance rules only for the variance you can justify and explain.
Use gaps (1, 10, 20, 50) so you can insert rules without renumbering your entire set.
Treat rule updates as production changes. Validate match rates and exception volume before committing.
A rule should document the variance it covers and the risk it introduces.
If a rule never matches, it may be unnecessary. If it matches too often, it may be too broad.
High tolerance increases false positives. Use it as a fallback and review results carefully.

Next steps