List all customers

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

GET $BASE_URL/v1/customers

Request headers

string

required

Your active Bearer token: Bearer <accessToken>. See Authentication for how to obtain and refresh tokens.

Query parameters

number

Page size. Defaults to 50, maximum 250.

string

Paging token from the previous response’s meta.cursor. See Pagination & filtering.

string

Case-insensitive substring match on the customer’s email. Minimum 5 characters.

string

Case-insensitive substring match on the customer’s phone. Minimum 5 characters.

number

Exact match on the customer’s status code. Comma-separate for IN: f[status]=1,2.

string

Exact match on the external identifier assigned to the customer. Comma-separate for IN.

Response fields (200 OK)

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

array

Array of customer records. Each element contains the fields below.

Show customer fields

string

Unique identifier of the customer record.

object

Customer profile fields (fullname, phone, email, …). Keys vary based on your organization’s form configuration.

object

Loyalty balances keyed by collectable key. Each entry has value (current spendable balance) and total (lifetime collected).

object

Free-form metadata attached to the customer record. Optional.

object

Customer consent flags recorded at registration or later updates. Optional.

string | null

External identifier from your own system, if assigned.

number

Status code of the customer record.

string

ISO 8601 creation timestamp. Omitted when not available.

string

ISO 8601 timestamp of the most recent update. Omitted when not available.

object

Paging information.

Show meta fields

number

Total record count for the current filter, independent of paging position.

number

Page size applied to this response.

string

Paging token for the next page. Omitted on the last page.

List items do not include the customer’s cards and coupons. Use GET /v1/customers/find to load a single customer with cards and active coupons.

curl --request GET \
  --url "$BASE_URL/v1/customers?f%5Bdata.phone%5D=531951&limit=2" \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

{
  "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
  }
}

{
  "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"
}

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.

Getting started

Endpoints

Reference

Request headers

Query parameters

Response fields (200 OK)

​Request headers

​Query parameters

​Response fields (200 OK)

Request headers

Query parameters

Response fields (200 OK)