Search via DB

POST

{collection}

filter

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions/filter" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ],
    "logical_operator": "and",
    "sort_by": "created_at",
    "sort_order": "desc",
    "include_count": true,
    "limit": 20,
    "offset": 0
  }'

{
  "data": [
    {
      "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
      "amount": 15000,
      "currency": "USD",
      "status": "APPLIED",
      "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
      "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 150
}

{
  "error": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull",
  "error_detail": {
    "code": "GEN_BAD_REQUEST",
    "message": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull"
  }
}

The Filter API lets you retrieve records from any collection using server-side filters with a clean JSON interface. Use it when you need precise, composable queries without the overhead of Typesense.

If you’re using the auto-provisioned Enterprise Core instance included with your Production License deployment, set the base URL to: https://ENTERPRISE_PUBLIC_URL/core.If you’re connecting to a different Core instance, use the publicly accessible base URL for that instance instead.

Authorization

If set, the API uses an API key for authentication. Include the following header in your requests: X-blnk-key: <api-key>. Replace <api-key> with your secret API key. Ensure the key is kept secure and not exposed in public repositories or client-side code. See also: Scoped API keys and Secure your Blnk server.

Path Parameters

string

required

The collection to filter. Supported values:

ledgers - Filter ledgers by name or metadata
balances - Filter balance records across all ledgers
transactions - Filter transaction records
identities - Filter customer identity records

Body

array

required

Array of filter objects. Each object has field, operator, and optionally value or values. Learn more: Search via DB docsExamples:

[{"field": "status", "operator": "eq", "value": "APPLIED"}] - Exact match
[{"field": "currency", "operator": "in", "values": ["USD", "EUR"]}] - Multiple values

string

Combines multiple filters with and or or. Default: and.

string

Field to sort by. Only indexed fields are sortable. Default: created_at. Learn more: Performance Tuning

string

Sort direction: asc or desc. Default: desc.

boolean

Include total count in response. May impact performance on large datasets. Default: false.

integer

Max records to return. Default: 20, max: 100.

integer

Records to skip for pagination. Default: 0.

Response

array

Array of matching records. Structure varies by collection type (ledger, balance, transaction, or identity).

integer

Total number of matching records. Only present when include_count is true.

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions/filter" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ],
    "logical_operator": "and",
    "sort_by": "created_at",
    "sort_order": "desc",
    "include_count": true,
    "limit": 20,
    "offset": 0
  }'

{
  "data": [
    {
      "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
      "amount": 15000,
      "currency": "USD",
      "status": "APPLIED",
      "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
      "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 150
}

{
  "error": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull",
  "error_detail": {
    "code": "GEN_BAD_REQUEST",
    "message": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull"
  }
}

For full-text search, advanced faceting, or querying across millions of records, use Search via Typesense instead.

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.

Update Metadata

Search via Typesense

curl -X POST "http://YOUR_BLNK_INSTANCE_URL/transactions/filter" \
  -H "X-Blnk-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ],
    "logical_operator": "and",
    "sort_by": "created_at",
    "sort_order": "desc",
    "include_count": true,
    "limit": 20,
    "offset": 0
  }'

{
  "data": [
    {
      "transaction_id": "txn_6164573b-6cc8-45a4-ad2e-7b4ba6a60f7d",
      "amount": 15000,
      "currency": "USD",
      "status": "APPLIED",
      "source": "bln_28edb3e5-c168-4127-a1c4-16274e7a28d3",
      "destination": "bln_ebcd230f-6265-4d4a-a4ca-45974c47f746",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "total_count": 150
}

{
  "error": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull",
  "error_detail": {
    "code": "GEN_BAD_REQUEST",
    "message": "Invalid filter: invalid operator 'resembles' for field 'amount': must be one of eq, ne, gt, gte, lt, lte, in, between, like, ilike, isnull, isnotnull"
  }
}

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Search

Transaction hooks

API keys

System

Authorization

Path Parameters

Body

Response

Need help?

​Authorization

​Path Parameters

​Body

​Response

​Need help?

Authorization

Path Parameters

Body

Response

Need help?