> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List all customers

> Returns paginated customers for the organization your access token is scoped to, with optional filters on email, phone, status, and opaqueId.

```http theme={null}
GET $BASE_URL/v1/customers
```

**Returns the customers associated with your access token's organization, newest first, in the standard [list envelope](/api/pagination) (`data` + `meta`). Deleted customers are excluded.**

> **Auth:** `Authorization: Bearer <accessToken>` — an organization-scoped token from [Authentication](/api/authentication).

### Query parameters

`limit` (default `50`, max `250`) and `cursor` follow the shared pagination contract — see [Pagination & filtering](/api/pagination).

### Filterable fields

Filters combine with each other (and with the organization scope) using AND.

| Field | Type | Match | Description |
| - | - | - | - |
| `f[data.email]` | string | contains (min 5) | Case-insensitive substring match on the customer's email. |
| `f[data.phone]` | string | contains (min 5) | Case-insensitive substring match on the customer's phone. |
| `f[status]` | number | exact / IN | Status code. Comma = IN (`f[status]=1,2`). |
| `f[opaqueId]` | string | exact / IN | External identifier assigned to the customer. Comma = IN. |

> In `contains` filters the comma is searched literally, and values below the minimum length return `invalid_filter_value` (400). Filtering on any other field returns `invalid_filter_field` (400).

### Example

```bash theme={null}
curl --request GET \
  --url "$BASE_URL/v1/customers?f%5Bdata.phone%5D=531951&limit=2" \
  --header 'Authorization: Bearer <accessToken>'
```

### Response

```json theme={null}
{
  "data": [
    {
      "id": "af3e927e-3d9a-4ba5-b9e9-dfb0c5ffecdd",
      "data": {
        "fullname": "Jane Doe",
        "phone": "+905319512211",
        "email": "jane@example.com"
      },
      "collectables": {
        "point_MMSR5": { "value": 1000, "total": 2760 }
      },
      "consents": { "privacy_policy": true },
      "opaqueId": null,
      "status": 1,
      "createdAt": "2026-07-24T12:56:03.702Z",
      "updatedAt": "2026-07-30T15:13:29.054Z"
    }
  ],
  "meta": {
    "total": 1,
    "limit": 2
  }
}
```

Notes:

* `meta.total` is the total record count for the current filter, independent of paging position; `meta.cursor` is the paging token for the next page and is omitted on the last page.
* List items do not include the customer's `cards` and `coupons`. Use [GET /v1/customers/find](/api/find-customer) to load a single customer with cards and active coupons.
* Optional fields that have no value are omitted — you will not receive `null`. Exception: `opaqueId` is `null` when not assigned.
* Use `collectables` to display loyalty balances (points, stamps) on your screen; avoid storing this data locally — BrandWallet is the single source of truth for loyalty data.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.