Filtering • Blnk Developer Documentation

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'status:=APPLIED && currency:=USD' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD"},
  blnkgo.Transactions,
)

Response

{
  "found": 15,
  "hits": [
    {
      "document": {
        "amount": 1500,
        "amount_string": "1500",
        "atomic": false,
        "currency": "USD",
        "status": "APPLIED",
        "created_at": 1720363463,
        "effective_date": 1720363463,
        "source": "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
        "destination": "bln_86ba7976-499d-4282-955e-a7c2abf5db12"
      }
    }
  ]
}

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'status:=APPLIED && currency:=USD' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'description:payment && reference:ref_001' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "description:payment && reference:ref_001"},
  blnkgo.Transactions,
)

Comparison operators

Compare numeric values and dates:

Operator	Meaning	Example
`>`	Greater than	`amount:>1000`
`>=`	Greater than or equal	`balance:>=5000`
`<`	Less than	`created_at:<1720396800`
`<=`	Less than or equal	`balance:<=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"
  }'

const response = await blnk.Search.search(
  { q: '*', filter_by: 'amount:>1000 && balance:<=50000' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "amount:>1000 && balance:<=50000"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  {
    q: '*',
    filter_by: 'balance:[1000..50000] && created_at:[1720310400..1720396800]',
  },
  'balances',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{
    Q:        "*",
    FilterBy: "balance:[1000..50000] && created_at:[1720310400..1720396800]",
  },
  blnkgo.Balances,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'status:[APPLIED, INFLIGHT] && currency:[USD, EUR]' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "status:[APPLIED, INFLIGHT] && currency:[USD, EUR]"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'status:=APPLIED && currency:=USD && amount:>1000' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD && amount:>1000"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'description:payment && reference:ref_001' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "description:payment && reference:ref_001"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'currency:!=USD && status:!=REJECTED' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "currency:!=USD && status:!=REJECTED"},
  blnkgo.Transactions,
)

Common patterns

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'status:[APPLIED, INFLIGHT]' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "status:[APPLIED, INFLIGHT]"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'amount:[1000..10000] && currency:=USD' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "amount:[1000..10000] && currency:=USD"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'created_at:[1720310400..1720396800]' },
  'transactions',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "created_at:[1720310400..1720396800]"},
  blnkgo.Transactions,
)

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

const response = await blnk.Search.search(
  { q: '*', filter_by: 'currency:[USD, EUR, GBP] && balance:>0' },
  'balances',
);

results, resp, err := client.Search.SearchDocument(
  blnkgo.SearchParams{Q: "*", FilterBy: "currency:[USD, EUR, GBP] && balance:>0"},
  blnkgo.Balances,
)

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.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Webhooks

API keys

Guides

Configuration

Advanced

Migration guides

Filtering Results

Quick start

Filter operators

Exact match (`:=`)

Partial match (`:`)

Comparison operators

Range operator (`[min..max]`)

IN operator (`[value1, value2]`)

AND operator (`&&`)

Partial match (`:`)

Not equal (`:!=`)

Common patterns

Best practices

Need help?

​Quick start

​Filter operators

​Exact match (:=)

​Partial match (:)

​Comparison operators

​Range operator ([min..max])

​IN operator ([value1, value2])

​AND operator (&&)

​Partial match (:)

​Not equal (:!=)

​Common patterns

​Best practices

​Need help?

Quick start

Filter operators

Exact match (`:=`)

Partial match (`:`)

Comparison operators

Range operator (`[min..max]`)

IN operator (`[value1, value2]`)

AND operator (`&&`)

Partial match (`:`)

Not equal (`:!=`)

Common patterns

Best practices

Need help?