​
Overview

In this guide, you’ll learn how to perform a simple one-to-one reconciliation workflow with Blnk. This includes:
  1. Preparing and uploading our data.
  2. Creating our matching rules.
  3. Running our reconciliation process.
  4. Review the reconciliation results.
For this example, we’ll use Postman or cURL to send our API requests. You can also refer to the API reference for details on the available endpoints.

​
Prerequisites

Before starting, ensure you have:
  1. A running Blnk server instance (e.g. at http://localhost:5001). Version 0.10.0 or later.

​
Recording sample transactions

First, import the following sample transactions using the Bulk Transactions feature: 
POST https://YOUR_BLNK_INSTANCE_URL/transactions/bulk
Request body
{
  "atomic": true,
  "inflight": false,
  "run_async": false,
  "transactions": [
    {
      "amount": 152.75,
      "precision": 100,
      "reference": "txn_001",
      "description": "Invoice settlement",
      "currency": "USD",
      "source": "@WorldA",
      "allow_overdraft": true,
      "destination": "@WorldB"
    },
    {
      "amount": 329.40,
      "precision": 100,
      "reference": "txn_002",
      "description": "Refund processing",
      "currency": "USD",
      "source": "@WorldB",
      "allow_overdraft": true,
      "destination": "@WorldA"
    },
    {
      "amount": 87.15,
      "precision": 100,
      "reference": "txn_003",
      "description": "Service charge",
      "currency": "USD",
      "source": "@WorldA",
      "allow_overdraft": true,
      "destination": "@WorldB"
    },
    {
      "amount": 413.60,
      "precision": 100,
      "reference": "txn_004",
      "description": "Payment for goods",
      "currency": "USD",
      "source": "@WorldB",
      "allow_overdraft": true,
      "destination": "@WorldA"
    },
    {
      "amount": 276.89,
      "precision": 100,
      "reference": "txn_005",
      "description": "Subscription fee",
      "currency": "USD",
      "source": "@WorldA",
      "allow_overdraft": true,
      "destination": "@WorldB"
    },
    {
      "amount": 199.99,
      "precision": 100,
      "reference": "txn_006",
      "description": "Expense reimbursement",
      "currency": "USD",
      "source": "@WorldB",
      "allow_overdraft": true,
      "destination": "@WorldA"
    },
    {
      "amount": 540.25,
      "precision": 100,
      "reference": "txn_007",
      "description": "Project funding",
      "currency": "USD",
      "source": "@WorldA",
      "allow_overdraft": true,
      "destination": "@WorldB"
    },
    {
      "amount": 135.70,
      "precision": 100,
      "reference": "txn_008",
      "description": "Loan repayment",
      "currency": "USD",
      "source": "@WorldB",
      "allow_overdraft": true,
      "destination": "@WorldA"
    },
    {
      "amount": 92.80,
      "precision": 100,
      "reference": "txn_009",
      "description": "Freelance payment",
      "currency": "USD",
      "source": "@WorldA",
      "allow_overdraft": true,
      "destination": "@WorldB"
    },
    {
      "amount": 480.55,
      "precision": 100,
      "reference": "txn_010",
      "description": "Revenue share",
      "currency": "USD",
      "source": "@WorldB",
      "allow_overdraft": true,
      "destination": "@WorldA"
    }
  ]
}

​
Preparing the external data

Next, download the sample CSV file provided below. This file will act as our external data source and has already been formatted to meet Blnk’s specifications. See External Data Preparation for more details.

External data source

Click to download sample CSV file.

​
Uploading the data

Upload your CSV file with the Upload Data endpoint: 
POST https://YOUR_BLNK_INSTANCE_URL/reconciliation/upload
or use cURL 
curl --location 'https://YOUR_BLNK_INSTANCE_URL/reconciliation/upload' \
--form 'file=@recon-example-external-source.csv' \
--form 'source=Stripe'
Response
{
  "record_count": 10,
  "source": "Stripe",
  "upload_id": "upload_0cd4a87d-544c-4b7e-9232-f36e79631c32"
}
Save the upload_id. You’ll need it to start the reconciliation.

​
Setting our matching rules

We’ll define rules to match internal and external transactions. For this example, we want:
  1. Amount Match: Exact amount match
  2. Currency Match: Exact matches for both fields.
  3. Reference Match: Exact matches for both references
All rules must be true for successful matching. Create the rule with this request: 
POST http://localhost:5001/reconciliation/matching-rules

{
    "name": "Basic matcher",
    "description": "Matches transactions by amount and reference",
    "criteria": [
        {
            "field": "amount",
            "operator": "equals"
        },
        {
            "field": "currency",
            "operator": "equals"
        },
        {
            "field": "reference",
            "operator": "equals"
        }
    ]
}
Save the rule_id for the reconciliation step.

​
Run reconciliation

With the external data uploaded and our matching rules configured, we’re ready to run our first reconciliation. In this example, we’ll use the Batch Reconciliation option and apply a one_to_one strategy to ensure precise matching. See Reconciliation Strategies for details. Send this request to start the reconciliation: 
POST https://YOUR_BLNK_INSTANCE_URL/reconciliation/start

{
    "upload_id": "upload_0cd4a87d-544c-4b7e-9232-f36e79631c32",
    "strategy": "one_to_one",
    "matching_rule_ids": [
        "rule_3d5ae6d4-6722-40c5-ac4b-0bd66ab7d363"
    ]
}

​
View reconciliation results

Finally, you can view the status of your reconciliation with the following endpoint: 
GET https://YOUR_BLNK_INSTANCE_URL/reconciliation/{reconciliation_id}
Response
{
  "reconciliation_id": "recon_f1df3e68-fd8d-4566-8670-891c3c1e7d58",
  "upload_id": "upload_0cd4a87d-544c-4b7e-9232-f36e79631c32",
  "status": "completed",
  "matched_transactions": 2,
  "unmatched_transactions": 8,
  "is_dry_run": false,
  "started_at": "2025-03-17T08:32:24.005476Z",
  "completed_at": "2025-03-17T08:32:24.062136Z"
}
FieldDescription
matched_transactionsNumber of external records matched.
unmatched_transactionsNumber of external records not matched.

​
Error handling

  1. 401 Unauthorized: Ensure your API key is correct and included in the Authorization header.
  2. 400 Bad Request: Check your request body or file format. For uploads, ensure the CSV matches Blnk’s specifications.
  3. 404 Not Found: Verify the endpoint URL (e.g., /reconciliation/upload for uploads, /reconciliation/start for reconciliation).

​
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.