Skip to main content
Available in version 0.6.1 and later.
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, faceting, 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:
  • Filter large datasets efficiently
  • Perform full-text searches across your data
  • Aggregate and count values with faceting
  • Sort and paginate results for better performance
  • Combine multiple search conditions in a single request

​
Searchable collections

The Search API works with four main collections in your Blnk ledger:
CollectionEndpointDescription
Transactions/search/transactionsSearch through all transaction records
Balances/search/balancesFind balance records across all ledgers
Ledgers/search/ledgersLocate specific ledgers by name or metadata
Identities/search/identitiesSearch 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: 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
    "query_by": "parent_transaction",
    "filter_by": "status:=APPLIED && currency:=USD",
    "sort_by": "created_at:desc",
    "page": 1,
    "per_page": 10
  }'
Response
{
  "facet_counts": [],
  "found": 2,
  "hits": [
    {
      "document": {
        "amount": 532,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test bulk",
        "destination": "bln_20666087-1355-4736-ba04-3ba92a7542b9",
        "id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5",
        "parent_transaction": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
        "precise_amount": 53200,
        "precision": 100,
        "reference": "bulk-search-1d2",
        "source": "bln_93fb50c2-969e-49c2-bb61-ef5ed245516e",
        "status": "APPLIED",
        "transaction_id": "txn_cd728825-a6e1-4fae-9277-c3235a045ea5"
      },
      "highlights": [
        {
          "field": "parent_transaction",
          "matched_tokens": ["bulk_baaea495-148a-4b16-b171-68c92fb911a6"],
          "snippet": "<mark>bulk_baaea495-148a-4b16-b171-68c92fb911a6</mark>"
        }
      ],
      "text_match": 578730123365711993
    },
    {
      "document": {
        "amount": 100,
        "created_at": 1758116489,
        "currency": "USD",
        "description": "Test bulk",
        "destination": "bln_d298f2b8-fdd6-4d0e-ade7-3cddcea90a8d",
        "id": "txn_0ae624a5-7fbc-4c67-831d-f888e928d4bc",
        "parent_transaction": "bulk_baaea495-148a-4b16-b171-68c92fb911a6",
        "precise_amount": 10000,
        "precision": 100,
        "reference": "bulk-search-2d3",
        "source": "bln_6592f225-f8fe-48cd-8974-51974dc83a3a",
        "status": "APPLIED",
        "transaction_id": "txn_0ae624a5-7fbc-4c67-831d-f888e928d4bc"
      },
      "highlights": [
        {
          "field": "parent_transaction",
          "matched_tokens": ["bulk_baaea495-148a-4b16-b171-68c92fb911a6"],
          "snippet": "<mark>bulk_baaea495-148a-4b16-b171-68c92fb911a6</mark>"
        }
      ],
      "text_match": 578730123365711993
    }
  ],
  "out_of": 232,
  "page": 1,
  "request_params": {
    "collection_name": "transactions",
    "per_page": 10,
    "q": "bulk_baaea495-148a-4b16-b171-68c92fb911a6"
  },
  "search_cutoff": false,
  "search_time_ms": 2
}

​
Request parameters

ParameterDescriptionRequiredType
qThe search query text. Use * to return all records. Learn moreYesstring
query_byComma-separated list of fields to search in. Learn moreNostring
filter_byFilter conditions to refine results. Learn moreNostring
facet_byComma-separated list of fields to aggregate and count. Learn moreNostring
sort_bySorting conditions for ordering results. Learn moreNostring
pagePage number for pagination. Starts at 1. Learn moreNointeger
per_pageNumber of results per page. Maximum 250, default 10. Learn moreNointeger

​
Response structure

FieldDescriptionType
foundTotal number of matching records.integer
hitsArray of search results, each containing a document with the record data.array
out_ofTotal number of records in the collection.integer
pageCurrent page number.integer
search_time_msTime taken to execute the search in milliseconds.integer
facet_countsAggregated counts for faceted fields. Only present when using facet_by. Learn morearray
highlightsSearch 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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "query_by": "source,destination",
    "sort_by": "created_at:desc"
  }'
2

Get recent high-value transactions

Find transactions above a certain amount threshold to monitor large money movements or flag suspicious activity.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "amount:>10000",
    "sort_by": "created_at:desc",
    "per_page": 50
  }'
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "created_at:[1704067200..1706745599]",
    "sort_by": "created_at:desc"
  }'
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "status:=REJECTED",
    "sort_by": "created_at:desc"
  }'
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "payment",
    "query_by": "meta_data.transaction_type,description",
    "sort_by": "created_at:desc"
  }'
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "source:=bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e && destination:=bln_86ba7976-499d-4282-955e-a7c2abf5db12",
    "sort_by": "created_at:desc"
  }'

​
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "balance:>100000",
    "sort_by": "balance:desc"
  }'
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*",
    "filter_by": "identity_id:=idt_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "sort_by": "created_at:desc"
  }'
3

Search ledgers by name or metadata

Find specific ledgers using partial name matching or metadata filters to locate the right ledger for operations.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/ledgers" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "customer savings",
    "query_by": "name",
    "sort_by": "created_at:desc"
  }'

​
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.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/identities" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "john doe",
    "query_by": "first_name,last_name,email",
    "sort_by": "created_at:desc"
  }'

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