Matching Rules

Matching rules are used by Blnk to determine how to compare and match your ledger records with your external records. These rules define how fields like amount, date, and reference are compared, with flexibility for small discrepancies (called drifts). In this guide, you’ll learn how to set matching rules and apply them when running reconciliation.

Creating a matching rule

To create a new matching rule, call the Create matching rule endpoint:

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/reconciliation/matching-rules" \
  -H "X-blnk-key: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Default matcher",
    "description": "Amount with 1% drift matcher",
    "criteria": [
      {
        "field": "amount",
        "operator": "equals",
        "allowable_drift": 0.01
      },
      {
        "field": "currency",
        "operator": "equals"
      },
      {
        "field": "date",
        "operator": "equals",
        "allowable_drift": 1800
      },
      {
        "field": "reference",
        "operator": "contains"
      }
    ]
  }'

const response = await blnk.Reconciliation.createMatchingRule({
  name: 'Default matcher',
  description: 'Amount with 1% drift matcher',
  criteria: [
    {
      field: 'amount',
      operator: 'equals',
      allowable_drift: 0.01,
    },
    {
      field: 'currency',
      operator: 'equals',
    },
    {
      field: 'date',
      operator: 'equals',
      allowable_drift: 1800,
    },
    {
      field: 'reference',
      operator: 'contains',
    },
  ],
});

rule, resp, err := client.Reconciliation.CreateMatchingRule(blnkgo.Matcher{
    Name: "Default matcher",
    Description: "Amount with 1% drift matcher",
    Criteria: []blnkgo.Criteria{
        {
            Field: blnkgo.CriteriaFieldAmount,
            Operator: blnkgo.ReconciliationOperatorEquals,
            AllowableDrift: 0.01,
        },
        {
            Field: blnkgo.CriteriaFieldCurrency,
            Operator: blnkgo.ReconciliationOperatorEquals,
        },
        {
            Field: blnkgo.CriteriaFieldDate,
            Operator: blnkgo.ReconciliationOperatorEquals,
            AllowableDrift: 1800,
        },
        {
            Field: blnkgo.CriteriaFieldReference,
            Operator: blnkgo.ReconciliationOperatorContains,
        },
    },
})

response = blnk.reconciliation.create_matching_rule({
  "name": "Default matcher",
  "description": "Amount with 1% drift matcher",
  "criteria": [
    {
      "field": "amount",
      "operator": "equals",
      "allowable_drift": 0.01,
    },
    {
      "field": "currency",
      "operator": "equals",
    },
    {
      "field": "date",
      "operator": "equals",
      "allowable_drift": 1800,
    },
    {
      "field": "reference",
      "operator": "contains",
    },
  ],
})

ApiResponse<JsonNode> response = blnk.reconciliation().createMatchingRule(
    Matcher.create()
        .name("Default matcher")
        .description("Amount with 1% drift matcher")
        .criteria(List.of(
            Criteria.create()
            .field("amount")
            .operator("equals")
            .allowableDrift(0.01),
            Criteria.create()
            .field("currency")
            .operator("equals"),
            Criteria.create()
            .field("date")
            .operator("equals")
            .allowableDrift(1800),
            Criteria.create()
            .field("reference")
            .operator("contains")
        )));

Response

{
  "rule_id": "rule_3d5ae6d4-6722-40c5-ac4b-0bd66ab7d363",
  "name": "Default matcher",
  "description": "Amount with 1% drift matcher",
  "created_at": "2024-02-20T05:28:03.558281542Z"
}

Editing and deleting matching rules

After creating a matching rule, you can update it or remove it when it’s no longer needed:

Update: Use the Update matching rule endpoint to change the name, description, or criteria of an existing rule.
Delete: Use the Delete matching rule endpoint to remove a rule from your reconciliation workflows.

How Blnk matches transactions during reconciliation

Blnk ensures accurate reconciliation by comparing external records with your ledger records based on five key attributes:

Attributes	Operators	What it does
`amount`	`equals`, `greater_than`, `less_than`	Compares transaction amounts.
`currency`	`equals`	Ensures both transactions use the same currency.
`date`	`equals`, `after`, `before`	Matches transactions based on their timestamps.
`reference`	`equals`, `contains`	Checks if the transaction reference matches or is partially included.
`description`	`equals`, `contains`	Matches transactions based on their descriptions.

Understanding matching operators

Each attribute is matched using specific operators, which determine how strict the comparison is:

Operators	Description
`equals`	Both records must match exactly.
`contains`	Parts of the external record match the internal record.
`greater_than`	The external amount must be higher than the internal amount.
`less_than`	The external amount must be lower than the internal amount.
`after`	The external date must be later than the internal date.
`before`	The external date must be earlier than the internal date.

Example scenarios

Here’s how these rules work during reconciliation:

Matching amounts

External amount	Internal amount	Operator used	Match?
$100.00	$100.00	`equals`	✅ Yes
$105.00	$100.00	`greater_than`	✅ Yes
$95.00	$100.00	`greater_than`	❌ No

Matching dates

External date	Internal date	Operator used	Match?
March 10, 2025	March 10, 2025	`equals`	✅ Yes
March 12, 2025	March 11, 2025	`after`	✅ Yes
March 10, 2025	March 11, 2025	`after`	❌ No

Matching references

External amount	Internal amount	Operator used	Match?
”REF-12345"	"12345”	`contains`	✅ Yes
”INV-56789"	"INV-56789”	`equals`	✅ Yes
”12345"	"REF-12345”	`contains`	❌ No

Why this matters

Flexibility: Use operators like contains, greater_than, and before to account for processing delays, fees, and partial matches.
Precision: Ensure transactions are matched accurately, reducing errors in reconciliation.
Control: Customize your matching rules to fit your financial workflows.

Handling discrepancies with drifts

Small differences in amounts or dates-like fees or time zone shifts-can disrupt reconciliation. The allowable_drift field sets a tolerance range for matches, used with the equals operator. Blnk supports two types:

Amount drift: Tolerates value differences (e.g., 0.01 = 1% drift).
A $100 internal record with 1% drift matches $99 – $101 external records.
Date drift: Allows for time differences (e.g., 3600 = 1 hour).
A 2:00 PM internal record with 1-hour drift matches 1:00–3:00 PM external timestamps.

When to use drifts

Use amount drift when:
- Your external data includes processing fees or minor exchange rate variations.
- Your system rounds transactions differently from external sources.
Use date drift when:
- Your transactions involve cross-time-zone processing.
- Payment settlements take hours or days to finalize.

Best practices

To ensure accurate and reliable financial reconciliation, follow these best practices when defining matching rules:

Optimize for efficiency: Reduce manual effort by implementing automated matching rules.
Use Drifts Strategically: Apply allowable drifts to handle small discrepancies without compromising accuracy.
Ensure accuracy: Minimize human errors with consistent and precise rule application.
Design for scalability: Use robust rules that can handle high transaction volumes and complex financial products.
Maintain compliance: Align matching rules with regulatory requirements for transparency.
Regularly review & optimize: Continuously assess and refine matching rules based on reconciliation performance and error patterns.
Audit logs: Maintain detailed logs of matching decisions to support audits and troubleshooting.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Creating a matching rule

Editing and deleting matching rules

How Blnk matches transactions during reconciliation

Understanding matching operators

Example scenarios

Why this matters

Handling discrepancies with drifts

When to use drifts

Best practices

Need help?

​Creating a matching rule

​Editing and deleting matching rules

​How Blnk matches transactions during reconciliation

​Understanding matching operators

​Example scenarios

​Why this matters

​Handling discrepancies with drifts

​When to use drifts

​Best practices

​Need help?

Creating a matching rule

Editing and deleting matching rules

How Blnk matches transactions during reconciliation

Understanding matching operators

Example scenarios

Why this matters

Handling discrepancies with drifts

When to use drifts

Best practices

Need help?