​
Overview

The querying parameters q and query_by work together to control what data you search for and which fields to search in. These parameters enable you to perform full-text searches, exact matches, and wildcard queries across your ledger data. The q parameter is required in all search requests. The query_by parameter is required when searching for specific terms, and optional only when using the wildcard *.

​
Quick start

Here’s a basic search query that demonstrates both parameters: 
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"
  }'

​
Query parameters

​
Exact text search

Search for specific text or IDs by specifying the fields to search in: 
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"
  }'
Use * to return all records (only case where query_by is optional): 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/balances" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "*"
  }'
Search for multiple words across specified fields: 
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 services",
    "query_by": "description"
  }'
Multi-word searches require ALL words to be present in the document. For “payment services”, both “payment” AND “services” must exist in the specified fields.

​
Single vs multiple fields

Search in one field or across multiple fields using comma separation: 
# Single field
{
  "q": "john",
  "query_by": "first_name"
}

# Multiple fields
{
  "q": "john doe",
  "query_by": "first_name,last_name,email"
}
Available in version 0.11.0 and later.
Search within metadata or nested objects using dot notation: 
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "transfer",
    "query_by": "meta_data.transaction_type,description"
  }'

​
Common patterns

1

Search for a specific balance's transactions

This finds all transactions where the specified 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"
  }'
2

Find customers by name or email

This searches for “alice” across name and email fields, useful for customer support.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/identities" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "alice",
    "query_by": "first_name,last_name,email"
  }'
3

Find transactions by description keywords

This finds transactions containing “refund” in their description or reference fields.
curl -X POST "http://YOUR_BLNK_INSTANCE_URL/search/transactions" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "refund",
    "query_by": "description,reference"
  }'

​
Best practices

  • Be specific with fields: Target relevant fields in query_by for better performance.
  • Validate field names: Invalid fields in query_by may return unexpected results.

Filtering

Learn how to combine queries with filters for more precise results.

Search overview

Return to the main Search API documentation for a complete overview.

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