Querying • Blnk Developer Documentation

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"
  }'

const response = await blnk.Search.search(
  { q: 'bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e', query_by: 'source,destination' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{
        Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
        QueryBy: "source,destination",
    },
    blnkgo.Transactions,
)

response = blnk.search.search(
  {"q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e", "query_by": "source,destination"},
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e")
        .queryBy("source,destination"),
    "transactions");

Response

{
  "found": 3,
    "hits": [
        {
            "document": {
                "amount": 5000,
                "amount_string": "5000",
                "atomic": false,
                "created_at": 1720363463,
                "currency": "USD",
                "description": "Payment for services",
                "destination": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
                "effective_date": 1720363463,
                "source": "bln_86ba7976-499d-4282-955e-a7c2abf5db12",
                "status": "APPLIED",
                "transaction_id": "txn_4c86b65e-8249-4b3b-8000-b907d32f9a9f"
            },
            "highlights": [
                {
          "field": "destination",
          "matched_tokens": ["bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e"],
          "snippet": "<mark>bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e</mark>"
        }
      ]
    }
  ]
}

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"
  }'

const response = await blnk.Search.search(
  {
    q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    query_by: "source,destination",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e", QueryBy: "source,destination"},
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "query_by": "source,destination",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e")
        .queryBy("source,destination"),
    "transactions");

Wildcard search

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": "*"
  }'

const response = await blnk.Search.search(
  {
    q: "*",
  },
  'balances',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "*"},
    blnkgo.Balances,
)

response = blnk.search.search(
  {
    "q": "*",
  },
  "balances",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("*"),
    "balances");

Multi-word search

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"
  }'

const response = await blnk.Search.search(
  {
    q: "payment services",
    query_by: "description",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "payment services", QueryBy: "description"},
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "payment services",
    "query_by": "description",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("payment services")
        .queryBy("description"),
    "transactions");

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"
}

Metadata search

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"
  }'

const response = await blnk.Search.search(
  {
    q: "transfer",
    query_by: "meta_data.transaction_type,description",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "transfer", QueryBy: "meta_data.transaction_type,description"},
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "transfer",
    "query_by": "meta_data.transaction_type,description",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("transfer")
        .queryBy("meta_data.transaction_type,description"),
    "transactions");

Common patterns

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"
  }'

const response = await blnk.Search.search(
  {
    q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    query_by: "source,destination",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e", QueryBy: "source,destination"},
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
    "query_by": "source,destination",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e")
        .queryBy("source,destination"),
    "transactions");

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"
  }'

const response = await blnk.Search.search(
  {
    q: "alice",
    query_by: "first_name,last_name,email",
  },
  'identities',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "alice", QueryBy: "first_name,last_name,email"},
    blnkgo.Identities,
)

response = blnk.search.search(
  {
    "q": "alice",
    "query_by": "first_name,last_name,email",
  },
  "identities",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("alice")
        .queryBy("first_name,last_name,email"),
    "identities");

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"
  }'

const response = await blnk.Search.search(
  {
    q: "refund",
    query_by: "description,reference",
  },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "refund", QueryBy: "description,reference"},
    blnkgo.Transactions,
)

response = blnk.search.search(
  {
    "q": "refund",
    "query_by": "description,reference",
  },
  "transactions",
)

ApiResponse<JsonNode> response = blnk.search().search(
    SearchParams.create()
        .q("refund")
        .queryBy("description,reference"),
    "transactions");

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.

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Querying Parameters

Quick start

Query parameters

Exact text search

Wildcard search

Multi-word search

Single vs multiple fields

Metadata search

Common patterns

Best practices

Need help?

​Quick start

​Query parameters

​Exact text search

​Wildcard search

​Multi-word search

​Single vs multiple fields

​Metadata search

​Common patterns

​Best practices

​Need help?

Quick start

Query parameters

Exact text search

Wildcard search

Multi-word search

Single vs multiple fields

Metadata search

Common patterns

Best practices

Need help?