Available in version 0.6.1 and later.

​
Overview

You can use Search to retrieve any data — ledgers, ledger balances, and transactions — from your Blnk Ledger. In this guide, you’ll learn the basics of sending search queries to Blnk and how we return responses.

​
Use the search endpoint URL

POST http://YOUR_URL/search/:collection
:collection refers to the collection of data you want to query. There are currently only 3 collections in Blnk:
  1. Ledgers (/search/ledgers).
  2. Ledger balances (/search/balances).
  3. Transactions (/search/transactions).

​
Input your search query

Send a request payload containing your search query. Consider the following example, a POST request to /search/balances:
Request
{
    "q": "*",
    "filter_by": "balance:>1000",
    "sort_by": "created_at:desc",
    "page": 2,
    "per_page": 50
}
FieldDescriptionRequiredExample
qThe query text to search for in the collection. Learn more about querying.Yes"*" returns all records in the transaction.
filter_byFilter conditions for refining your results.Nobalance:>1000 returns all ledger balances with their balance value greater than “1000.”
sort_bySorting conditions that will be used to order your results.Nocreated_at:desc orders the results in by the “created_at” field in descending order.
pageThe page number of your results.No2 returns the second page of the results.
per_pageThe number of results per page.No50 returns only 50 results on one page; to see the rest (if any), you’ll need to move to the next page.
Your query is processed and the results are presented in the following response format:
Response
{
    "found": 1,
    "out_of": 1,
    "page": 1,
    "request_params": {
        "q": "*",
        "filter_by": "balance:>1000",
        "sort_by": "created_at:desc",
        "page": 2,
        "per_page": 50
    },
    "search_time_ms": 1,
    "hits": [
        {
            "document": {
                "balance_id": "bln_0be360ca-86fe-457d-be43-daa3f966d8f0",
                "balance": 0,
                "credit_balance": 0,
                "debit_balance": 0,
                "currency": "USD",
                "precision": 1,
                "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
                "created_at": "2024-02-20 05:28:03 UTC",
                "meta_data": null
            }
        }
    ]
}
FieldDescription
foundNumber of documents that match your search query and filtering conditions.
out_ofNumber of documents that match only your search query.
pageThe page being displayed to you.
request_paramsYour request payload.
search_time_msTime it took for the search query to execute, usually in ms.
hitsContains an array of your search results.
documentRepresents the actual search result item.

​
2. Understanding search query

​
Structure and terminology

A query clause consists of a field followed by an operator and then a value.
TermsExample
clause"q": "*"
field"q"
operator:
value"*"

​
Quotes

You must always use quotation marks around string values in your query. You can omit them for numerical values.
  • "filter_by": "balance:>1000" means quotes are required because the value is a string.
  • "per_page": 50 doesn’t need quotes because it is a numerical value.

​
3. Supported parameters

The parameters you can specify in the value part of your query clause are determined by the collection you are searching in. There are three data collections in the current version of the Blnk Ledger — ledgers, ledger balances, and transactions.

​
For ledgers

ParametersSample usage
namename:World
ledger_idledger_id:=ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc
created_atcreated_at:<2024-20-01

​
For balances

ParametersSample usage
balance_idbalance_id:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0
balancebalance:[100..100000]
credit_balancecredit_balance:>100000
debit_balancedebit_balance:=2000000
currencycurrency:[USD, GBP, EUR]
precisionprecision:=100
ledger_idledger_id:=ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc
created_atcreated_at:<2024-20-01

​
For transactions

ParametersSample usage
idid:=txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d
sourcesource:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0
destinationdestination:=bln_0be360ca-86fe-457d-be43-daa3f966d8f0
referencereference:=ref_001adcfgf
amountamount:[2000..100000]
currencycurrency:[USD, GBP, EUR]
statusstatus:[applied, queued]
created_atcreated_at:<2024-20-01
scheduled_forscheduled_for:>2024-20-01
allow_over_draftallow_over_draft:!=true
inflightinflight:=true

​
4. Key considerations

​
Processing time

The time it takes to process a search query may vary depending on the kind and complexity of your search query. For workflows where you need to display values in real-time like balances or a specific transaction details, used the GET by id endpoints specific to the collection you are searching for.

​
Data freshness

It is advisable not to use read-after-write flows (for example, searching immediately after a transaction request has been made) because the data may not be available immediately to search. Under normal conditions, data is searchable within seconds, but propagation of new or updated data could be delayed due to unforeseen circumstances.

Querying parameters

Filtering parameters

Sorting parameters

Pagination 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.