Available in version 0.13.2 and later.
Blnk’s Filter API lets you retrieve exactly the data you need from any collection. Use server-side filters with a clean JSON interface to build precise, composable queries.
The Filter API is available for all collections: ledgers, balances, transactions, and identities.
Filter endpoints Each collection has a dedicated filter endpoint:
Collection Endpoint Ledgers POST /ledgers/filterBalances POST /balances/filterTransactions POST /transactions/filterIdentities POST /identities/filter
Send a POST request with a JSON body containing your filters, sorting, and pagination options:
curl -X POST "https://YOUR_BLNK_INSTANCE_URL/transactions/filter" \ -H "X-Blnk-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filters": [ { "field": "status", "operator": "eq", "value": "APPLIED" }, { "field": "currency", "operator": "in", "values": ["USD", "EUR"] } ], "sort_by": "created_at", "sort_order": "desc", "include_count": true, "limit": 20, "offset": 0 }'
Parameter Type Required Description filtersarray Yes Array of filter objects sort_bystring No Field to sort by (default: created_at) sort_orderstring No Sort direction: asc or desc (default: desc) include_countboolean No Include total count in response (default: false) limitinteger No Max records to return (default: 20, max: 100) offsetinteger No Records to skip (default: 0)
The response format depends on whether include_count is enabled.
include_count: true
include_count: false (default)
{ "data" : [ { "transaction_id" : "txn_abc123" , "amount" : 15000 , "currency" : "USD" , "status" : "APPLIED" , "source" : "bln_source123" , "destination" : "bln_dest456" , "created_at" : "2024-01-15T10:30:00Z" } ], "total_count" : 150 }
If include_count is true, an additional query will run to fetch the total count, which may impact performance on large datasets.
Filter object Each filter in the filters array follows this structure:
Field Type Required Description fieldstring Yes The field to filter on operatorstring Yes The comparison operator valueany For single-value ops The value to compare against valuesarray For in/between ops Array of values (for those operators)
Supported operators Blnk provides a range of operators to match, compare, and filter your data precisely:
Operator Description Example eqEqual to {"field": "status", "operator": "eq", "value": "APPLIED"}neNot equal to {"field": "status", "operator": "ne", "value": "VOID"}gtGreater than {"field": "amount", "operator": "gt", "value": 1000}gteGreater than or equal {"field": "amount", "operator": "gte", "value": 1000}ltLess than {"field": "amount", "operator": "lt", "value": 5000}lteLess than or equal {"field": "amount", "operator": "lte", "value": 5000}inIn a set of values {"field": "currency", "operator": "in", "values": ["USD", "EUR"]}betweenBetween two values {"field": "amount", "operator": "between", "values": [1000, 5000]}likePattern match (case-sensitive) {"field": "name", "operator": "like", "value": "%savings%"}ilikePattern match (case-insensitive) {"field": "name", "operator": "ilike", "value": "%USD%"}isnullField is null {"field": "identity_id", "operator": "isnull"}isnotnullField is not null {"field": "identity_id", "operator": "isnotnull"}
For like and ilike operators, use % as a wildcard. %savings% matches any value containing “savings”. For isnull/isnotnull, the value property is ignored.
Sorting Control how results are ordered using the sort_by and sort_order parameters:
Parameter Values Default Description sort_byAny indexed field created_atField to sort by sort_orderasc, descdescSort direction
Only indexed fields (e.g., created_at, balance_id, etc.) are sortable. Sorting on non-indexed fields returns a 400 error.
For information on which fields are indexed and how to add custom indexes, see Performance Tuning .
Manage large result sets with pagination:
Parameter Default Max Description limit20100Max records to return offset0- Records to skip
To iterate through all pages, increment the offset by your limit value with each request. For example, with limit=50: page 1 uses offset=0, page 2 uses offset=50, page 3 uses offset=100, and so on.
Filterable fields Each collection exposes specific fields you can filter on. Select a tab below to see the available fields for each collection.
Transactions
Balances
Ledgers
Identities
Field Type Description transaction_idstring Unique transaction identifier referencestring Custom reference amountnumber Transaction amount currencystring Currency code statusstring QUEUED, APPLIED, INFLIGHT, VOID sourcestring Source balance ID destinationstring Destination balance ID created_attimestamp Creation time descriptionstring Transaction description balance_idstring Related balance (for internal mapping) meta_data.*any Custom metadata fields
Field Type Description balance_idstring Balance identifier ledger_idstring Parent ledger identity_idstring Associated identity indicatorstring Balance alias currencystring Currency code balancenumber Current balance credit_balancenumber Total credits debit_balancenumber Total debits created_attimestamp Creation time meta_data.*any Custom metadata fields
Field Type Description ledger_idstring Ledger identifier namestring Ledger name created_attimestamp Creation time meta_data.*any Custom metadata fields
Field Type Description identity_idstring Identity identifier first_namestring First name last_namestring Last name email_addressstring Email identity_typestring Identity type categorystring Category countrystring Country created_attimestamp Creation time meta_data.*any Custom metadata fields
To filter on custom metadata, use dot notation for the field name:
curl -X POST "https://YOUR_BLNK_INSTANCE_URL/transactions/filter" \ -H "X-Blnk-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "filters": [ { "field": "meta_data.customer_type", "operator": "eq", "value": "premium" } ] }'
Error handling Invalid filters return a 400 Bad Request:
{ "error" : "invalid field 'amount_string' for collection 'transactions'" }
Common issues:
Invalid field name for the collectionUnsupported operator Incorrect value type for the fieldMissing required filter properties
Best practices
Use specific filters : The more specific your filters, the faster your queries. Combine multiple filters to narrow results.
Paginate large results : Always use pagination when expecting many results. This improves performance and reduces response times.
Use include_count sparingly : Only request counts when necessary, as it adds overhead on large datasets.
Use appropriate operators : Use eq for exact matches, ilike for case-insensitive searches, and in for multiple values.
Consider Typesense for complex queries : For advanced operations like grouping, joins, or full-text search, consider using the Search API instead.
Optimize indexes : For frequently filtered or sorted fields, ensure proper indexes are in place. See Performance Tuning for details.
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 .
Tip: Connect to Blnk Cloud to see your Core data.You can view your transactions, manage identities, create custom reports, invite other team members to collaborate, and perform operations on your Core — all in one dashboard. Check out Blnk Cloud → 
