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": {
     "fields": ["amount", "currency", "date"]
   }
 }'

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "type": "EXACT",
  "priority": 1,
  "config": {
    "fields": ["amount", "currency", "date"]
  },
  "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": {
     "tolerancePercent": 1.0,
     "toleranceAbsolute": 5.0
   }
 }'
Example:
  • Transaction A: $1,000.00
  • Transaction B: $1,008.00
  • Variance: 0.8% → Matches (within 1% 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
   }
 }'

​
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": "550e8400-e29b-41d4-a716-446655440000",
      "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
      "type": "EXACT",
      "priority": 1,
      "config": {
        "fields": ["amount", "currency", "date"]
      },
      "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 PUT "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": {
     "tolerancePercent": 2.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

Exception routing

Configure classification, assignment, and escalation for unmatched transactions.

Confidence scoring

Understand how scores are calculated and how thresholds impact automation.