Skip to main content
POST
/
ledgers
/
filter
curl -X POST https://YOUR_BLNK_INSTANCE_URL/ledgers/filter \
  -H 'Content-Type: application/json' \
  -H 'X-Blnk-Key: YOUR_API_KEY' \
  -d '{
    "filters": [
      {
        "field": "name",
        "operator": "ilike",
        "value": "%wallet%"
      }
    ],
    "limit": 20,
    "offset": 0
  }'

[
  {
    "ledger_id": "ldg_0a3b7c7e-e7a8-4f1e-9f6a-3d4c8b2e1a5f",
    "name": "Customer Wallets",
    "created_at": "2024-01-15T10:30:00Z",
    "meta_data": {
      "region": "US",
      "project_id": "proj_123"
    }
  },
  {
    "ledger_id": "ldg_1b4c8d8f-f8b9-5g2f-0g7b-4e5d9c3f2b6g",
    "name": "Business Wallets",
    "created_at": "2024-01-20T09:15:00Z",
    "meta_data": {
      "region": "US",
      "project_id": "proj_456"
    }
  }
]
Filter ledgers using a flexible JSON-based filtering system with support for complex queries, pagination, and optional result counting.

​
Request Body

​
filters
array
required
Array of filter objects defining the search criteria. Each filter object contains:
  • field (string, required): The ledger field to filter on (e.g., “name”, “created_at”, “ledger_id”)
  • operator (string, required): The comparison operator to use
  • value (any, required): The value to compare against
​
limit
integer
default:"10"
Maximum number of ledgers to return. Must be at least 1.
​
offset
integer
default:"0"
Number of ledgers to skip before starting to return results. Must be 0 or greater.
​
include_count
boolean
default:"false"
When true, the response includes a total_count field with the total number of matching ledgers.

​
Available Operators

  • eq - Equal to
  • neq - Not equal to
  • gt - Greater than
  • gte - Greater than or equal to
  • lt - Less than
  • lte - Less than or equal to
  • like - Pattern matching (case-sensitive)
  • ilike - Pattern matching (case-insensitive)
  • in - Value is in array
  • nin - Value is not in array

​
Filterable Fields

  • ledger_id - The unique identifier of the ledger
  • name - The ledger name
  • created_at - The creation timestamp
  • Any custom field in meta_data (use dot notation, e.g., “meta_data.region”)

​
Response

When include_count is false (default), returns an array of ledger objects. When include_count is true, returns an object with:
​
data
array
Array of ledger objects matching the filter criteria
​
total_count
integer
Total number of ledgers matching the filter criteria (only present when include_count is true)
curl -X POST https://YOUR_BLNK_INSTANCE_URL/ledgers/filter \
  -H 'Content-Type: application/json' \
  -H 'X-Blnk-Key: YOUR_API_KEY' \
  -d '{
    "filters": [
      {
        "field": "name",
        "operator": "ilike",
        "value": "%wallet%"
      }
    ],
    "limit": 20,
    "offset": 0
  }'

[
  {
    "ledger_id": "ldg_0a3b7c7e-e7a8-4f1e-9f6a-3d4c8b2e1a5f",
    "name": "Customer Wallets",
    "created_at": "2024-01-15T10:30:00Z",
    "meta_data": {
      "region": "US",
      "project_id": "proj_123"
    }
  },
  {
    "ledger_id": "ldg_1b4c8d8f-f8b9-5g2f-0g7b-4e5d9c3f2b6g",
    "name": "Business Wallets",
    "created_at": "2024-01-20T09:15:00Z",
    "meta_data": {
      "region": "US",
      "project_id": "proj_456"
    }
  }
]

​
Usage Notes

  • The filters array is required and must contain at least one filter object
  • Multiple filters are combined with AND logic (all conditions must match)
  • Use ilike with % wildcards for flexible text searching (e.g., %wallet% matches “Customer Wallets”)
  • Date comparisons should use ISO 8601 format (e.g., “2024-01-01T00:00:00Z”)
  • The in and nin operators expect an array value (e.g., {"field": "name", "operator": "in", "value": ["Ledger A", "Ledger B"]})
  • Set include_count: true when you need to show total results for pagination UI
  • For metadata filtering, use dot notation to access nested fields (e.g., “meta_data.region”)
  • This endpoint is more flexible than query-based filtering but requires a POST request
  • Consider using GET /ledgers with query parameters for simpler filtering needs

Build docs developers (and LLMs) love

Get started for freeTalk to us