Skip to main content
The Filters API lets you retrieve filtered records from a Blnk Core instance through Blnk Cloud. Send a POST request with a JSON filter body to query instance data directly. For the full endpoint reference, see Filters API.

​
How it works

  • Requests query the instance database directly through Blnk Cloud.
  • Every request must include instance_id as a query parameter.
  • You authenticate using a Cloud access token with the data:read scope.
  • Filter conditions are sent as a JSON array in the request body.

​
URL structure

Base URL: 
https://api.cloud.blnkfinance.com
Filter endpoints are at the API root, not under /data/ or /proxy/. Required headers: 
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Every request must include instance_id as a query parameter: 
?instance_id=YOUR_INSTANCE_ID

​
Filter endpoints

Each collection has a dedicated filter endpoint:
CollectionEndpointDefault pageSize
LedgersPOST /ledger/filter30
BalancesPOST /balances/filter20
TransactionsPOST /transactions/filter20
IdentitiesPOST /identities/filter20
ReconciliationsPOST /reconciliation/filter20
The ledgers endpoint uses /ledger/filter (singular), not /ledgers/filter.

​
Request format

Send a POST request with a JSON body containing your filters. Pagination is controlled via query parameters, not the request body. 
curl -X POST "https://api.cloud.blnkfinance.com/transactions/filter?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ]
  }'
ParameterLocationRequiredDescription
filtersBodyYesArray of filter objects
instance_idQueryYesTarget Core instance ID
pageQueryNoPage number (default: 1)
pageSizeQueryNoRecords per page (default varies by resource)
strict_totalQueryNoTransactions only. Set to true for an exact total count

​
Filter object

Each filter object in the filters array has the following fields:
FieldTypeRequiredDescription
fieldstringYesField to filter on
operatorstringYesComparison operator
valueanyNoSingle value for most operators
valuesarrayNoMultiple values for in and between operators

​
Supported operators

OperatorMeaningExample
eqEquals{ "field": "status", "operator": "eq", "value": "APPLIED" }
neNot equals{ "field": "status", "operator": "ne", "value": "PENDING" }
gtGreater than{ "field": "amount", "operator": "gt", "value": 100 }
gteGreater than or equal{ "field": "amount", "operator": "gte", "value": 50 }
ltLess than{ "field": "amount", "operator": "lt", "value": 500 }
lteLess than or equal{ "field": "amount", "operator": "lte", "value": 500 }
inIn list{ "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
betweenBetween two values{ "field": "created_at", "operator": "between", "values": ["2025-01-01T00:00:00Z", "2025-01-31T23:59:59Z"] }
likePattern match{ "field": "reference", "operator": "like", "value": "ref_%" }
ilikeCase-insensitive pattern{ "field": "description", "operator": "ilike", "value": "%fee%" }
isnullIs null{ "field": "identity_id", "operator": "isnull" }
isnotnullIs not null{ "field": "identity_id", "operator": "isnotnull" }
existsJSON key exists (metadata){ "field": "meta_data.myApp.channel", "operator": "exists" }
notexistsJSON key absent (metadata){ "field": "meta_data.myApp.channel", "operator": "notexists" }

​
Response format

{
  "data": [
    {
      "transaction_id": "txn_c4e70eb8-e4d6-4e04-a2e2-92a43b969e0c",
      "amount": 100.50,
      "currency": "USD",
      "status": "APPLIED",
      "created_at": "2025-01-15T10:00:00.000000000Z"
    }
  ],
  "total": 12,
  "stats": {},
  "total_is_estimate": false,
  "total_source": "exact"
}
The Cloud Filters API uses { "filters": [...] } in the body with pagination via query parameters. This differs from the self-hosted Core Filter API, which accepts limit, offset, sort_by, and include_count in the body. See Search via Database Filtering for self-hosted Core.

​
Filterable fields by 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. Example: meta_data.myApp.channel.