Available in version 0.6.1 and later.
Overview
The Blnk Search API enables you to retrieve one or more records from your ledger. You can search across ledgers, balances, transactions, and identities using its filtering, sorting, and full-text search capabilities. Unlike the standard GET endpoints that return either all records or a single specific record, the Search API gives you more control over your results. Use it when you need to:- Find specific records based on multiple criteria
- Filter large datasets efficiently
- Perform full-text searches across your data
- Sort and paginate results for better performance
- Combine multiple search conditions in a single request
For simple operations like retrieving a single transaction by ID or listing all balances, use the standard GET endpoints. For everything else that requires filtering, searching, or complex queries, use the Search API.
Searchable collections
The Search API works with four main collections in your Blnk ledger:Collection | Endpoint | Description |
---|---|---|
Transactions | /search/transactions | Search through all transaction records |
Balances | /search/balances | Find balance records across all ledgers |
Ledgers | /search/ledgers | Locate specific ledgers by name or metadata |
Identities | /search/identities | Search customer identity records |
Quick start
To get started with the Search API, use the endpoint:/search/{collection}
where collection can be ledgers
, balances
, identities
, or transactions
.
Here’s how a full search request looks:
Request parameters
Parameter | Description | Required | Type |
---|---|---|---|
q | The search query text. Use * to return all records. Learn more | Yes | string |
query_by | Comma-separated list of fields to search in. Learn more | No | string |
filter_by | Filter conditions to refine results. Learn more | No | string |
sort_by | Sorting conditions for ordering results. Learn more | No | string |
page | Page number for pagination. Starts at 1. Learn more | No | integer |
per_page | Number of results per page. Maximum 250, default 10. Learn more | No | integer |
Response structure
Field | Description | Type |
---|---|---|
found | Total number of matching records. | integer |
hits | Array of search results, each containing a document with the record data. | array |
out_of | Total number of records in the collection. | integer |
page | Current page number. | integer |
search_time_ms | Time taken to execute the search in milliseconds. | integer |
highlights | Search term highlighting information for matched fields. | array |
Common use cases
1. Transaction analysis
1
Find all transactions for a specific account
Get a complete transaction history by searching for all transactions where a particular balance ID appears as either source or destination.
2
Get recent high-value transactions
Find transactions above a certain amount threshold to monitor large money movements or flag suspicious activity.
3
Search transactions by date range
Retrieve all transactions that occurred within a specific time period for reporting or audit purposes. Use Unix timestamps for date filtering.
Learn more about date filtering and Unix timestamps in our Filtering documentation.
4
Find rejected transactions
Filter transactions by status to identify failed payments that were rejected due to insufficient funds or validation errors.
For advanced filtering with operators like
:=
, &&
, and ranges, see our detailed Filtering guide.5
Search by transaction type or description
Use full-text search to find transactions based on transaction type in metadata or descriptions for customer support.
Learn more about full-text search and field-specific queries in our Querying documentation.
6
Find transactions between specific accounts
Search for transactions that occurred between two particular balance IDs to track money flow or analyze trading patterns.
2. Account management
1
Get balances above/below a threshold
Find all balances with amounts greater than or less than specific values for risk management or account monitoring.
2
Fetch all balances belonging to an identity
Retrieve all balances associated with a specific identity ID to get a complete view of a user’s accounts and wallets.
3
Search ledgers by name or metadata
Find specific ledgers using partial name matching or metadata filters to locate the right ledger for operations.
3. Customer support
1
Search identities by name or email
Find specific customer identities using partial name matching or email addresses for customer support and account verification.
Learn more
Now that you understand the basics of the Search API, dive deeper into specific topics:Querying
Learn how to use the
q
and query_by
parameters for full-text search and field-specific queries.Filtering
Master advanced filtering with operators, ranges, and complex conditions using
filter_by
.Sorting
Control result ordering with single and multi-field sorting using
sort_by
.Pagination
Efficiently handle large result sets with
page
and per_page
parameters.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 →