Skip to main content
Filters balances using advanced criteria specified in a JSON request body. Provides more sophisticated filtering capabilities than the query parameter approach, including sorting, counting, and complex filter combinations.

​
Request Body

​
filters
array
required
Array of filter conditions to apply. All filters use AND logic.
​
limit
integer
default:"20"
Maximum number of results to return.
​
offset
integer
default:"0"
Number of results to skip for pagination.
​
sort_by
string
Field to sort results by.Example: created_at, balance, currency
​
sort_order
string
default:"asc"
Sort direction.Options:
  • asc: Ascending order
  • desc: Descending order
​
include_count
boolean
default:"false"
Include total count of matching records in response.

​
Response

​
Without Count

Returns an array of balance objects matching the filters.
​
[]
array
Array of balance objects.

​
With Count

When include_count: true, returns an object with data and count.
​
data
array
Array of balance objects matching the filters.
​
total_count
integer
Total number of balances matching the filter criteria (before pagination).

​
Examples

{
  "filters": [
    {
      "field": "currency",
      "operator": "eq",
      "value": "USD"
    }
  ],
  "limit": 50,
  "offset": 0
}

​
cURL Examples

curl -X POST https://api.blnk.io/balances/filter \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      {"field": "currency", "operator": "eq", "value": "USD"}
    ],
    "limit": 50
  }'

​
Response Examples

Without Count
[
  {
    "balance_id": "bal_123abc",
    "ledger_id": "ldg_456def",
    "currency": "USD",
    "balance": "50000",
    "credit_balance": "100000",
    "debit_balance": "50000",
    "created_at": "2024-01-15T10:30:00Z"
  },
  {
    "balance_id": "bal_456def",
    "ledger_id": "ldg_456def",
    "currency": "USD",
    "balance": "75000",
    "credit_balance": "150000",
    "debit_balance": "75000",
    "created_at": "2024-01-16T14:20:00Z"
  }
]
With Count
{
  "data": [
    {
      "balance_id": "bal_123abc",
      "ledger_id": "ldg_456def",
      "currency": "USD",
      "balance": "50000"
    }
  ],
  "total_count": 1247
}

​
Use Cases

​
Find High-Value Balances

Identify balances above a certain threshold: 
{
  "filters": [
    {
      "field": "balance",
      "operator": "gte",
      "value": "1000000"
    }
  ],
  "sort_by": "balance",
  "sort_order": "desc",
  "limit": 100
}

​
Multi-Currency Reporting

Get balances for specific currencies: 
{
  "filters": [
    {
      "field": "currency",
      "operator": "in",
      "values": ["USD", "EUR", "GBP"]
    }
  ],
  "include_count": true
}

​
Ledger-Specific Analysis

Analyze balances within specific ledgers: 
{
  "filters": [
    {
      "field": "ledger_id",
      "operator": "eq",
      "value": "ldg_customer_accounts"
    },
    {
      "field": "balance",
      "operator": "gt",
      "value": "0"
    }
  ],
  "sort_by": "balance",
  "sort_order": "desc"
}

​
Recent Balances

Find recently created balances: 
{
  "filters": [
    {
      "field": "created_at",
      "operator": "gte",
      "value": "2024-03-01T00:00:00Z"
    }
  ],
  "sort_by": "created_at",
  "sort_order": "desc",
  "limit": 50
}

​
Zero Balance Accounts

Find balances with zero or negative balance: 
{
  "filters": [
    {
      "field": "balance",
      "operator": "lte",
      "value": "0"
    }
  ],
  "include_count": true
}

​
Filter Operators

​
Equality Operators

// Exact match
{"field": "currency", "operator": "eq", "value": "USD"}

// Not equal
{"field": "currency", "operator": "neq", "value": "USD"}

​
Comparison Operators

// Greater than
{"field": "balance", "operator": "gt", "value": "100000"}

// Greater than or equal
{"field": "balance", "operator": "gte", "value": "100000"}

// Less than
{"field": "balance", "operator": "lt", "value": "100000"}

// Less than or equal
{"field": "balance", "operator": "lte", "value": "100000"}

​
List Operators

// In list
{
  "field": "ledger_id",
  "operator": "in",
  "values": ["ldg_123", "ldg_456", "ldg_789"]
}

​
Pattern Matching

// Like (pattern matching)
{"field": "indicator", "operator": "like", "value": "%@example.com"}

​
Pagination

Handle large result sets with pagination: 
// Page 1
{
  "filters": [...],
  "limit": 100,
  "offset": 0,
  "include_count": true
}

// Page 2
{
  "filters": [...],
  "limit": 100,
  "offset": 100
}

// Page 3
{
  "filters": [...],
  "limit": 100,
  "offset": 200
}
Use total_count from the first request to calculate total pages: 
const totalPages = Math.ceil(total_count / limit);

​
Sorting

Sort results by any field: 
// Sort by balance (highest first)
{
  "sort_by": "balance",
  "sort_order": "desc"
}

// Sort by creation date (newest first)
{
  "sort_by": "created_at",
  "sort_order": "desc"
}

// Sort by currency (alphabetical)
{
  "sort_by": "currency",
  "sort_order": "asc"
}

​
Performance Considerations

  • Indexed Fields: Filters on currency, ledger_id, and created_at are optimized
  • Balance Filters: Filtering by balance amounts may be slower on large datasets
  • Limit Results: Use reasonable limit values (100-1000) for best performance
  • Count Queries: include_count: true adds overhead, use only when needed
  • Pagination: Use offset-based pagination for consistent results

​
Error Responses

Invalid Filter
{
  "error": "invalid filter field: invalid_field"
}
Invalid Operator
{
  "error": "invalid operator: invalid_op"
}
Missing Required Field
{
  "errors": ["filters is required"]
}

Build docs developers (and LLMs) love

Get started for freeTalk to us