Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt

Use this file to discover all available pages before exploring further.

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?

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.