Skip to main content

Overview

The filter_by parameter refines your search results based on specific field values. Use filters to narrow down large datasets and find exactly what you’re looking for. Filters work with any search query, including the wildcard *, and support various operators for different data types.

Quick start

Here’s a basic filter that demonstrates the most common pattern:
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:=APPLIED && currency:=USD"
  }'

Filter operators

Exact match (:=)

Match field values exactly:
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:=APPLIED && currency:=USD"
  }'

Partial match (:)

Match fields containing the value:
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": "description:payment && reference:ref_001"
  }'

Comparison operators

Compare numeric values and dates:
OperatorMeaningExample
>Greater thanamount:>1000
>=Greater than or equalbalance:>=5000
<Less thancreated_at:<1720396800
<=Less than or equalbalance:<=50000
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:>1000 && balance:<=50000"
  }'

Range operator ([min..max])

Filter values within a range:
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:[1000..50000] && created_at:[1720310400..1720396800]"
  }'
Use Unix timestamps for date ranges. The example above filters for July 7-8, 2024.

IN operator ([value1, value2])

Match any value from a list:
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:[APPLIED, INFLIGHT] && currency:[USD, EUR]"
  }'

AND operator (&&)

Combine multiple conditions where ALL must be true:
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:=APPLIED && currency:=USD && amount:>1000"
  }'

Partial match (:)

Match fields containing the value:
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": "description:payment && reference:ref_001"
  }'

Not equal (:!=)

Exclude specific values:
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": "currency:!=USD && status:!=REJECTED"
  }'

Common patterns

1

Filter by transaction status

Find all successful and pending transactions.
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:[APPLIED, INFLIGHT]"
  }'
2

Filter transactions by amount range

Find USD transactions between $1,000 and $10,000.
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:[1000..10000] && currency:=USD"
  }'
3

Filter by creation date

Find transactions created within a specific date range using Unix timestamps.
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:[1720310400..1720396800]"
  }'
4

Filter by multiple currencies

Find balances in major currencies with positive amounts.
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": "currency:[USD, EUR, GBP] && balance:>0"
  }'

Best practices

  • Use exact matches (:=) for IDs, statuses, and currencies
  • Combine with AND (&&) for precise filtering
  • Use ranges for amounts and dates instead of multiple comparisons
  • Test complex filters with simple queries first


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.