Skip to main content

​
Endpoint

POST /reconciliation/start
Starts a reconciliation process to match uploaded external transactions with internal Blnk transactions using the specified matching rules.

​
Request Body

​
upload_id
string
required
The unique identifier of the uploaded external data (obtained from the upload endpoint)
​
strategy
string
required
The reconciliation strategy to use. Supported values:
  • one_to_one: Match one external transaction to one internal transaction
  • one_to_many: Match one external transaction to multiple internal transactions
  • many_to_one: Match multiple external transactions to one internal transaction
​
matching_rule_ids
array
required
Array of matching rule IDs to apply during reconciliation. Rules are applied in order
​
grouping_criteria
string
Field to use for grouping transactions before matching (e.g., “date”, “reference”, “currency”)
​
dry_run
boolean
default:"false"
If true, performs the reconciliation without saving results. Useful for testing matching rules

​
Response

​
reconciliation_id
string
The unique identifier for this reconciliation process. Use this to check the status and retrieve results

​
Example Request

​
Basic One-to-One Reconciliation

{
  "upload_id": "upl_abc123def456",
  "strategy": "one_to_one",
  "matching_rule_ids": ["rule_xyz789"],
  "dry_run": false
}

​
Dry Run with Grouping

{
  "upload_id": "upl_abc123def456",
  "strategy": "one_to_many",
  "matching_rule_ids": ["rule_xyz789", "rule_abc456"],
  "grouping_criteria": "date",
  "dry_run": true
}

​
Multiple Rules with Currency Grouping

{
  "upload_id": "upl_abc123def456",
  "strategy": "one_to_one",
  "matching_rule_ids": ["rule_primary", "rule_fallback"],
  "grouping_criteria": "currency",
  "dry_run": false
}

​
Example Response

{
  "reconciliation_id": "rec_123abc456def"
}

​
Checking Reconciliation Status

Use the Get Reconciliation endpoint with the returned reconciliation_id to check the status and results. 
curl -X GET "https://api.blnk.io/reconciliation/rec_123abc456def" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Error Responses

​
error
string
Error message describing what went wrong

​
Common Errors

  • 400 Bad Request: Invalid request body or missing required fields
  • 500 Internal Server Error: Failed to start reconciliation process

​
Reconciliation Strategies

​
One-to-One

Matches a single external transaction to a single internal transaction. This is the most common strategy and is ideal for:
  • Direct payment matches
  • Invoice payments
  • Individual transfers

​
One-to-Many

Matches a single external transaction to multiple internal transactions. Useful for:
  • Batch payments that split into multiple internal entries
  • Aggregated deposits
  • Payment processors that bundle multiple transactions

​
Many-to-One

Matches multiple external transactions to a single internal transaction. Useful for:
  • Split payments from multiple sources
  • Installment payments
  • Partial settlements

​
Best Practices

  1. Always start with dry_run: Test your matching rules before committing
  2. Use grouping for large datasets: Group by date or currency to improve performance
  3. Order rules by specificity: Place more specific rules first in the array
  4. Monitor reconciliation status: Check the status regularly for long-running reconciliations

Build docs developers (and LLMs) love

Get started for freeTalk to us