> ## 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 Data

> Retrieve filtered records from a Blnk Core instance using JSON filters through Blnk Cloud.

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 <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

The Filters API lets you retrieve filtered records from a Blnk Core instance through Blnk Cloud. Send a POST request with a JSON filter body to query instance data directly.

For the full endpoint reference, see [Filters API](/cloud/reference/filters-api).

### How it works

* Requests query the instance database directly through Blnk Cloud.
* Every request must include `instance_id` as a query parameter.
* You authenticate using a Cloud access token with the `data:read` scope.
* Filter conditions are sent as a JSON array in the request body.

### URL structure

**Base URL:**

```bash theme={"system"}
https://api.cloud.blnkfinance.com
```

Filter endpoints are at the API root, not under `/data/` or `/proxy/`.

**Required headers:**

```bash theme={"system"}
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
```

Every request must include `instance_id` as a query parameter:

```bash theme={"system"}
?instance_id=YOUR_INSTANCE_ID
```

***

## Filter endpoints

Each collection has a dedicated filter endpoint:

| Collection      | Endpoint                      | Default pageSize |
| --------------- | ----------------------------- | ---------------- |
| Ledgers         | `POST /ledger/filter`         | 30               |
| Balances        | `POST /balances/filter`       | 20               |
| Transactions    | `POST /transactions/filter`   | 20               |
| Identities      | `POST /identities/filter`     | 20               |
| Reconciliations | `POST /reconciliation/filter` | 20               |

<Note>
  The ledgers endpoint uses `/ledger/filter` (singular), not `/ledgers/filter`.
</Note>

***

## Request format

Send a POST request with a JSON body containing your filters. Pagination is controlled via query parameters, not the request body.

```bash wrap theme={"system"}
curl -X POST "https://api.cloud.blnkfinance.com/transactions/filter?instance_id=YOUR_INSTANCE_ID&page=1&pageSize=20" \
  -H "Authorization: Bearer blnk_at_YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": [
      { "field": "status", "operator": "eq", "value": "APPLIED" },
      { "field": "currency", "operator": "in", "values": ["USD", "EUR"] }
    ]
  }'
```

| Parameter      | Location | Required | Description                                               |
| -------------- | -------- | -------- | --------------------------------------------------------- |
| `filters`      | Body     | Yes      | Array of filter objects                                   |
| `instance_id`  | Query    | Yes      | Target Core instance ID                                   |
| `page`         | Query    | No       | Page number (default: `1`)                                |
| `pageSize`     | Query    | No       | Records per page (default varies by resource)             |
| `strict_total` | Query    | No       | Transactions only. Set to `true` for an exact total count |

### Filter object

Each filter object in the `filters` array has the following fields:

| Field      | Type   | Required | Description                                      |
| ---------- | ------ | -------- | ------------------------------------------------ |
| `field`    | string | Yes      | Field to filter on                               |
| `operator` | string | Yes      | Comparison operator                              |
| `value`    | any    | No       | Single value for most operators                  |
| `values`   | array  | No       | Multiple values for `in` and `between` operators |

***

## Supported operators

| Operator    | Meaning                    | Example                                                                                                        |
| ----------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `eq`        | Equals                     | `{ "field": "status", "operator": "eq", "value": "APPLIED" }`                                                  |
| `ne`        | Not equals                 | `{ "field": "status", "operator": "ne", "value": "PENDING" }`                                                  |
| `gt`        | Greater than               | `{ "field": "amount", "operator": "gt", "value": 100 }`                                                        |
| `gte`       | Greater than or equal      | `{ "field": "amount", "operator": "gte", "value": 50 }`                                                        |
| `lt`        | Less than                  | `{ "field": "amount", "operator": "lt", "value": 500 }`                                                        |
| `lte`       | Less than or equal         | `{ "field": "amount", "operator": "lte", "value": 500 }`                                                       |
| `in`        | In list                    | `{ "field": "currency", "operator": "in", "values": ["USD", "EUR"] }`                                          |
| `between`   | Between two values         | `{ "field": "created_at", "operator": "between", "values": ["2025-01-01T00:00:00Z", "2025-01-31T23:59:59Z"] }` |
| `like`      | Pattern match              | `{ "field": "reference", "operator": "like", "value": "ref_%" }`                                               |
| `ilike`     | Case-insensitive pattern   | `{ "field": "description", "operator": "ilike", "value": "%fee%" }`                                            |
| `isnull`    | Is null                    | `{ "field": "identity_id", "operator": "isnull" }`                                                             |
| `isnotnull` | Is not null                | `{ "field": "identity_id", "operator": "isnotnull" }`                                                          |
| `exists`    | JSON key exists (metadata) | `{ "field": "meta_data.myApp.channel", "operator": "exists" }`                                                 |
| `notexists` | JSON key absent (metadata) | `{ "field": "meta_data.myApp.channel", "operator": "notexists" }`                                              |

***

## Response format

<CodeGroup>
  ```json Transactions wrap theme={"system"}
  {
    "data": [
      {
        "transaction_id": "txn_c4e70eb8-e4d6-4e04-a2e2-92a43b969e0c",
        "amount": 100.50,
        "currency": "USD",
        "status": "APPLIED",
        "created_at": "2025-01-15T10:00:00.000000000Z"
      }
    ],
    "total": 12,
    "stats": {},
    "total_is_estimate": false,
    "total_source": "exact"
  }
  ```

  ```json Balances and identities wrap theme={"system"}
  {
    "data": [
      {
        "balance_id": "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f",
        "currency": "USD",
        "balance": 10050,
        "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc"
      }
    ],
    "total": 5,
    "stats": {}
  }
  ```

  ```json Ledgers wrap theme={"system"}
  {
    "data": [
      {
        "ledger_id": "ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc",
        "name": "My Integration Ledger",
        "created_at": "2024-02-20T05:28:03.558281542Z"
      }
    ],
    "total": 3
  }
  ```
</CodeGroup>

<Info>
  The Cloud Filters API uses `{ "filters": [...] }` in the body with pagination via query parameters. This differs from the self-hosted Core Filter API, which accepts `limit`, `offset`, `sort_by`, and `include_count` in the body. See [Search via Database Filtering](/search/db/filtering) for self-hosted Core.
</Info>

***

## Filterable fields by resource

| Resource     | Fields                                                                                                                                                                                                                                                               |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Ledgers      | `ledger_id`, `name`, `created_at`, `meta_data`, `meta_data.<path>`                                                                                                                                                                                                   |
| Balances     | `balance_id`, `ledger_id`, `identity_id`, `indicator`, `currency`<br />`balance`, `credit_balance`, `debit_balance`<br />`inflight_balance`, `inflight_credit_balance`, `inflight_debit_balance`<br />`created_at`, `meta_data`                                      |
| Transactions | `transaction_id`, `parent_transaction`, `amount`, `currency`<br />`source`, `destination`, `balance_id`, `reference`<br />`status`, `created_at`, `effective_date`, `precision`, `meta_data`                                                                         |
| Identities   | `identity_id`, `first_name`, `last_name`, `other_names`, `gender`, `dob`<br />`email_address`, `phone_number`, `nationality`, `street`, `country`<br />`state`, `organization_name`, `category`, `identity_type`<br />`post_code`, `city`, `created_at`, `meta_data` |

<Note>
  Nested `meta_data` keys use dot notation. Example: `meta_data.myApp.channel`.
</Note>

***

<CtaCallout title="Need help building your app?" href="https://blnkfinance.com/contact/us?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=apps-help" buttonLabel="Get Pro Support" trackingEvent="clicked_pro_support">
  We help you build custom apps for your use case or get help building your own from scratch.
</CtaCallout>