Skip to main content

​
Overview

The Data API lets you read, query, and filter data stored in a Blnk Core instance through Blnk Cloud. It provides read-only access to Core data and is commonly used for dashboards, analytics, reporting, and back-office operations.

​
How it works

  • All requests go through Blnk Cloud, not directly to Core.
  • Every request must target a specific Core instance using instance_id.
  • You authenticate using a Cloud access token.
  • Blnk Cloud routes the request to the correct Core instance and returns the response.

​
URL structure

Base URL: 
https://api.cloud.blnkfinance.com/data
Required headers: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Every request must always include instance_id as a query parameter. 
?instance_id=YOUR_INSTANCE_ID

​
Listing resources

To list ledgers, balances, transactions, or identities, the general pattern is: 
curl -X GET "https://api.cloud.blnkfinance.com/data/{resource}?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN"
page and pageSize are optional. If you omit them, defaults apply:
  • page=1
  • pageSize=30 for ledgers, pageSize=20 for balances, transactions, and identities.
ResourcePath
Ledgers/ledgers
Balances/balances
Transactions/transactions
Identities/identities
For example, to list transactions: 
curl -X GET "https://api.cloud.blnkfinance.com/data/transactions?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN"

​
Fetch resource details

To retrieve details for a single ledger, balance, transaction, or identity by ID, use the detail routes. The general pattern is: 
curl -X GET "https://api.cloud.blnkfinance.com/data/{resource}/{resource_id}?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN"
ResourcePath
Ledger/data/ledgers/:ledger_id
Balance/data/balances/:balance_id
Transaction/data/transactions/:transaction_id
Identity/data/identities/:identity_id
curl -X GET "https://api.cloud.blnkfinance.com/data/transactions/txn_c4e70eb8-e4d6-4e04-a2e2-92a43b969e0c?instance_id=YOUR_INSTANCE_ID" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN"

​
Working with filters

The Data API uses suffixes on field names to express filter operators. Instead of sending operators as separate parameters, you append a suffix to the field name to indicate how the value should be compared. 
{field}_{operator}=value
For example: 
currency_eq=USD
amount_gte=50
status_ne=PENDING
Each filter is passed as a query parameter. Multiple filters can be combined in a single request.
The following parameters are reserved for pagination, sorting, or routing and must not be used as filter fields:
  • page, pageSize, per_page, limit, offset
  • sort, order, order_by, order_dir
  • instance_id, org_id

​
Supported operators

OperatorSuffixMeaningExample
Equal_eqequalscurrency_eq=USD
Not equal_nenot equalsstatus_ne=PENDING
Greater than_gt>amount_gt=100
Greater/eq_gte≥amount_gte=50
Less than_lt<amount_lt=500
Less/eq_lte≤amount_lte=500
In_inin liststatus_in=APPLIED,SCHEDULED
Between_betweenbetweencreated_at_between=2025-01-01T00:00:00Z|2025-01-31T23:59:59Z
Like_likepattern matchreference_like=ref_%
ILike_ilikecase-insensitivedescription_ilike=%fee%

​
Operator-specific rules

  1. BETWEEN:
    • Provide two values separated by a single pipe |
    • Encode the pipe as %7C in URLs
    Example
    created_at_between=2025-01-01T00:00:00%7C2025-01-31T23:59:59Z
  2. IN:
    • Provide comma-separated values
    Example
    currency_in=USD,EUR,GBP`
  3. LIKE / ILIKE:
    • Use SQL-style wildcards.
    • % matches any sequence of characters.
    • _ matches a single character.
    Example
    reference_like=ref_%
description_ilike=%fee%

​
Example: Filtering transactions

Here’s an example of how filter operators can be used together in a request: 
GET /data/transactions?
  instance_id=YOUR_INSTANCE_ID&
  currency_eq=USD&
  amount_gte=50&
  amount_lte=500&
  created_at_between=2025-01-01T00:00:00%7C2025-01-31T23:59:59Z

​
Filterable fields by resource

The table below lists the fields you can use for filtering on each Data API resource.
ResourceFields
Ledgersledger_id, name, created_at, meta_data, meta_data.<path>
Balancesbalance_id, ledger_id, identity_id, indicator, currency
balance, credit_balance, debit_balance
inflight_balance, inflight_credit_balance, inflight_debit_balance
created_at, meta_data
Transactionstransaction_id, parent_transaction, amount, currency
source, destination, balance_id, reference
status, created_at, effective_date, precision, meta_data
Identitiesidentity_id, first_name, last_name, other_names, gender, dob
email_address, phone_number, nationality, street, country
state, organization_name, category, identity_type
post_code, city, created_at, meta_data
Nested meta_data keys use dot notation, and the operator suffix goes at the end. Example: meta_data.myApp.channel_eq=web.

​
Need help?

If you’re having trouble with Blnk Cloud, don’t hesitate to send us a message via email at [email protected] or send us a message here.