> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Filtering Results
> Learn how to use the filter_by parameter to refine search results with precise conditions
export const RelatedTopics = ({title = "Related topics", items = []}) => {
if (!items.length) {
return null;
}
return ;
};
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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:
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'status:=APPLIED && currency:=USD' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "status:=APPLIED && currency:=USD"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("status:=APPLIED && currency:=USD"),
"transactions");
```
```json Response theme={"system"}
{
"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:
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'status:=APPLIED && currency:=USD' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "status:=APPLIED && currency:=USD"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("status:=APPLIED && currency:=USD"),
"transactions");
```
### Partial match (`:`)
Match fields containing the value:
```bash cURL wrap theme={"system"}
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_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: '*',
filter_by: 'description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{
Q: "*",
FilterBy: "description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{
"q": "*",
"filter_by": "description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy(
"description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94"),
"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` |
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'amount:>1000 && balance:<=50000' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "amount:>1000 && balance:<=50000"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "amount:>1000 && balance:<=50000"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("amount:>1000 && balance:<=50000"),
"transactions");
```
### Range operator (`[min..max]`)
Filter values within a range:
```bash cURL wrap theme={"system"}
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]"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: '*',
filter_by: 'balance:[1000..50000] && created_at:[1720310400..1720396800]',
},
'balances',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{
Q: "*",
FilterBy: "balance:[1000..50000] && created_at:[1720310400..1720396800]",
},
blnkgo.Balances,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{
"q": "*",
"filter_by": "balance:[1000..50000] && created_at:[1720310400..1720396800]",
},
"balances",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("balance:[1000..50000] && created_at:[1720310400..1720396800]"),
"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:
```bash cURL wrap theme={"system"}
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]"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'status:[APPLIED, INFLIGHT] && currency:[USD, EUR]' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "status:[APPLIED, INFLIGHT] && currency:[USD, EUR]"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "status:[APPLIED, INFLIGHT] && currency:[USD, EUR]"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("status:[APPLIED, INFLIGHT] && currency:[USD, EUR]"),
"transactions");
```
### AND operator (`&&`)
Combine multiple conditions where ALL must be true:
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'status:=APPLIED && currency:=USD && amount:>1000' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "status:=APPLIED && currency:=USD && amount:>1000"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "status:=APPLIED && currency:=USD && amount:>1000"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("status:=APPLIED && currency:=USD && amount:>1000"),
"transactions");
```
### Partial match (`:`)
Match fields containing the value:
```bash cURL wrap theme={"system"}
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_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{
q: '*',
filter_by: 'description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94',
},
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{
Q: "*",
FilterBy: "description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{
"q": "*",
"filter_by": "description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94",
},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy(
"description:payment && reference:ref_f482a1b3-6c2d-4e89-a17b-3d5e8f2a1c94"),
"transactions");
```
### Not equal (`:!=`)
Exclude specific values:
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'currency:!=USD && status:!=REJECTED' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "currency:!=USD && status:!=REJECTED"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "currency:!=USD && status:!=REJECTED"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("currency:!=USD && status:!=REJECTED"),
"transactions");
```
***
## Common patterns
Find all successful and pending transactions.
```bash cURL wrap theme={"system"}
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]"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'status:[APPLIED, INFLIGHT]' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "status:[APPLIED, INFLIGHT]"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "status:[APPLIED, INFLIGHT]"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("status:[APPLIED, INFLIGHT]"),
"transactions");
```
Find USD transactions between \$1,000 and \$10,000.
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'amount:[1000..10000] && currency:=USD' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "amount:[1000..10000] && currency:=USD"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "amount:[1000..10000] && currency:=USD"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("amount:[1000..10000] && currency:=USD"),
"transactions");
```
Find transactions created within a specific date range using Unix timestamps.
```bash cURL wrap theme={"system"}
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]"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'created_at:[1720310400..1720396800]' },
'transactions',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "created_at:[1720310400..1720396800]"},
blnkgo.Transactions,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "created_at:[1720310400..1720396800]"},
"transactions",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("created_at:[1720310400..1720396800]"),
"transactions");
```
Find balances in major currencies with positive amounts.
```bash cURL wrap theme={"system"}
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"
}'
```
```typescript TypeScript wrap theme={"system"}
const response = await blnk.Search.search(
{ q: '*', filter_by: 'currency:[USD, EUR, GBP] && balance:>0' },
'balances',
);
```
```go Go wrap theme={"system"}
results, resp, err := client.Search.SearchDocument(
blnkgo.SearchParams{Q: "*", FilterBy: "currency:[USD, EUR, GBP] && balance:>0"},
blnkgo.Balances,
)
```
```python Python wrap theme={"system"}
response = blnk.search.search(
{"q": "*", "filter_by": "currency:[USD, EUR, GBP] && balance:>0"},
"balances",
)
```
```java Java wrap theme={"system"}
ApiResponse response = blnk.search().search(
SearchParams.create()
.q("*")
.filterBy("currency:[USD, EUR, GBP] && balance:>0"),
"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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.