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

`GET /v1/customers` returns the customers associated with your access token's organization, newest first. Results come back in the standard [list envelope](/api/pagination) (`data` + `meta`), and can be filtered by email, phone, status, or `opaqueId`. Deleted customers are excluded.

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

## Request headers

<ParamField header="Authorization" type="string" required>
  Your active Bearer token: `Bearer <accessToken>`. See [Authentication](/api/authentication) for how to obtain and refresh tokens.
</ParamField>

## Query parameters

<ParamField query="limit" type="number">
  Page size. Defaults to `50`, maximum `250`.
</ParamField>

<ParamField query="cursor" type="string">
  Paging token from the previous response's `meta.cursor`. See [Pagination & filtering](/api/pagination).
</ParamField>

<ParamField query="f[data.email]" type="string">
  Case-insensitive substring match on the customer's email. Minimum 5 characters.
</ParamField>

<ParamField query="f[data.phone]" type="string">
  Case-insensitive substring match on the customer's phone. Minimum 5 characters.
</ParamField>

<ParamField query="f[status]" type="number">
  Exact match on the customer's status code. Comma-separate for IN: `f[status]=1,2`.
</ParamField>

<ParamField query="f[opaqueId]" type="string">
  Exact match on the external identifier assigned to the customer. Comma-separate for IN.
</ParamField>

## Response fields (200 OK)

The response is a JSON envelope with `data` (array of customer records) and `meta` (paging information).

<ResponseField name="data" type="array">
  Array of customer records. Each element contains the fields below.

  <Expandable title="customer fields">
    <ResponseField name="id" type="string">
      Unique identifier of the customer record.
    </ResponseField>

    <ResponseField name="data" type="object">
      Customer profile fields (`fullname`, `phone`, `email`, ...). Keys vary based on your organization's form configuration.
    </ResponseField>

    <ResponseField name="collectables" type="object">
      Loyalty balances keyed by collectable key. Each entry has `value` (current spendable balance) and `total` (lifetime collected).
    </ResponseField>

    <ResponseField name="metaData" type="object">
      Free-form metadata attached to the customer record. Optional.
    </ResponseField>

    <ResponseField name="consents" type="object">
      Customer consent flags recorded at registration or later updates. Optional.
    </ResponseField>

    <ResponseField name="opaqueId" type="string | null">
      External identifier from your own system, if assigned.
    </ResponseField>

    <ResponseField name="status" type="number">
      Status code of the customer record.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp. Omitted when not available.
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp of the most recent update. Omitted when not available.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  Paging information.

  <Expandable title="meta fields">
    <ResponseField name="total" type="number">
      Total record count for the current filter, independent of paging position.
    </ResponseField>

    <ResponseField name="limit" type="number">
      Page size applied to this response.
    </ResponseField>

    <ResponseField name="cursor" type="string">
      Paging token for the next page. Omitted on the last page.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  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.
</Note>

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

<ResponseExample>
  ```json 200 OK 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
    }
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "statuscode": 400,
    "errorcode": 400,
    "message": "invalid_filter_field",
    "description": "'barcode' is not filterable. Allowed filters: data.email, data.phone, status, opaqueId",
    "timestamp": 1754040000000,
    "path": "/v1/customers",
    "method": "GET"
  }
  ```
</ResponseExample>

<Tip>
  Use the customer's `collectables` field to display loyalty balances (points, stamps) on your screen. Avoid storing this data locally — BrandWallet is the single source of truth for all CRM and loyalty data.
</Tip>