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

# List All Customers

> Retrieve all customers with pagination, filtering, and relationship inclusion.

This endpoint retrieves a list of all customers with support for pagination, filtering, and including related data.

<Note>
  There is no `search` parameter on this endpoint. To find customers by name
  or phone, use the `filters` parameter described below.
</Note>

## HTTP Request

```http theme={null}
GET https://integrations.clopos.com/open-api/v2/customers
```

<Warning>
  This endpoint requires authentication. Include your JWT in the `x-token` header. See [Authentication](/authentication) for how to obtain a token and [Errors](/errors) for error responses.
</Warning>

## Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination (1-based).
</ParamField>

<ParamField query="limit" type="integer" default="50">
  Number of customers to return per page (1-999).
</ParamField>

<ParamField query="with[]" type="string">
  Include related data in the response. Supported values: `group`. You can include multiple `with` parameters.
</ParamField>

<ParamField query="filters" type="array">
  Filter customers by specific fields. Filters use array notation:
  `filters[0][0]=field_name&filters[0][1]=value`. Multiple filters can be
  combined using different indices (e.g., `filters[0]`, `filters[1]`).
  **Supported filter fields:** - `name`: Filter by customer name (partial
  match) - `phones`: Filter by phone number (searches in all phone numbers) -
  `group_id`: Filter by customer group ID **Filter Examples:** - Filter by
  name: `filters[0][0]=name&filters[0][1]=John` - Filter by phone:
  `filters[0][0]=phones&filters[0][1]=15551234567` - Multiple filters:
  `filters[0][0]=name&filters[0][1]=John&filters[1][0]=phones&filters[1][1]=15551234567`
</ParamField>

## Request Examples

<CodeGroup>
  ```bash curl (Basic Request) theme={null}
  curl --location "https://integrations.clopos.com/open-api/v2/customers?page=1&limit=50" \
    -H "x-token: oauth_example_token" \
  ```

  ```bash curl (With Filters and Relations) theme={null}
  curl --location --globoff 'https://integrations.clopos.com/open-api/v2/customers?page=1&limit=50&with[0]=group&filters[0][0]=name&filters[0][1]=John&filters[1][0]=phones&filters[1][1]=15551234567' \
    -H "x-token: oauth_example_token" \
  ```

  ```javascript javascript theme={null}
  // Basic request
  const params = new URLSearchParams({
      page: "1",
      limit: "50",
  });

  // With filters and relations
  const paramsWithFilters = new URLSearchParams({
      page: "1",
      limit: "50",
      "with[0]": "group",
      "filters[0][0]": "name",
      "filters[0][1]": "John",
      "filters[1][0]": "phones",
      "filters[1][1]": "15551234567",
  });

  const response = await fetch(
      `https://integrations.clopos.com/open-api/v2/customers?${paramsWithFilters}`,
      {
          headers: {
              "x-token": "oauth_example_token",
          },
      },
  );

  const customers = await response.json();
  ```

  ```python python theme={null}
  import requests

  url = "https://integrations.clopos.com/open-api/v2/customers"
  headers = {
      "x-token": "oauth_example_token",
  }

  # Basic request
  params = {
      "page": 1,
      "limit": 50
  }

  # With filters and relations
  params_with_filters = {
      "page": 1,
      "limit": 50,
      "with[0]": "group",
      "filters[0][0]": "name",
      "filters[0][1]": "John",
      "filters[1][0]": "phones",
      "filters[1][1]": "15551234567"
  }

  response = requests.get(url, headers=headers, params=params_with_filters)
  customers = response.json()
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
    "success": true,
    "data": [
        {
            "id": 1,
            "venue_id": 1,
            "cid": "1266eb42-9bdb-4e93-9fe0-3603c110f128",
            "group_id": 5,
            "name": "Rahid Akhundzada",
            "discount": 0,
            "email": null,
            "phones": [],
            "phone": "+994505355757",
            "address": null,
            "description": null,
            "address_data": [],
            "spent": 1162.8,
            "total_discount": 1.7,
            "total_bonus": 0,
            "receipt_count": 9,
            "gender": 1,
            "date_of_birth": null,
            "code": null,
            "source": null,
            "reference_id": null,
            "status": true,
            "can_use_loyalty_system": false,
            "is_verified": false,
            "created_at": "2026-01-31T16:23:27.000000Z",
            "updated_at": "2026-03-12T16:37:15.000000Z"
        },
        {
            "id": 2,
            "venue_id": 1,
            "cid": "24d7865f-f1bc-4948-be6a-e497d20bad0c",
            "group_id": 1,
            "name": "Reyal",
            "discount": 0,
            "email": null,
            "phones": [],
            "phone": null,
            "address": null,
            "description": null,
            "address_data": [],
            "spent": 714,
            "total_discount": 0,
            "total_bonus": 0,
            "receipt_count": 10,
            "gender": null,
            "date_of_birth": null,
            "code": null,
            "source": null,
            "reference_id": null,
            "status": true,
            "can_use_loyalty_system": false,
            "is_verified": false,
            "created_at": "2026-02-02T19:45:10.000000Z",
            "updated_at": "2026-02-02T23:37:33.000000Z"
        }
    ],
    "total": 7
}
```

## Field Reference

### Customer Object

| Field                    | Type               | Description                                                          |
| ------------------------ | ------------------ | -------------------------------------------------------------------- |
| `id`                     | integer            | Unique customer identifier.                                          |
| `cid`                    | string             | UUID identifier for the customer.                                    |
| `venue_id`               | integer            | The venue this customer belongs to.                                  |
| `group_id`               | integer            | The ID of the customer group they belong to.                         |
| `name`                   | string             | Customer's full name.                                                |
| `email`                  | string (nullable)  | Customer's email address.                                            |
| `phone`                  | string (nullable)  | Primary phone number.                                                |
| `phones`                 | array              | Additional phone numbers.                                            |
| `address`                | string (nullable)  | Customer's address.                                                  |
| `address_data`           | array              | Structured address entries with type, source, and formatted address. |
| `description`            | string (nullable)  | Additional notes about the customer.                                 |
| `discount`               | number             | Customer-level discount value.                                       |
| `spent`                  | number             | Total amount spent by the customer.                                  |
| `total_discount`         | number             | Total discount amount received across all receipts.                  |
| `total_bonus`            | number             | Total bonus amount used.                                             |
| `receipt_count`          | integer            | Total number of receipts for the customer.                           |
| `gender`                 | integer (nullable) | Gender: `1` = male, `2` = female, `null` = unspecified.              |
| `date_of_birth`          | string (nullable)  | Date of birth in `YYYY-MM-DD` format.                                |
| `code`                   | string (nullable)  | Customer code/identifier.                                            |
| `source`                 | string (nullable)  | Where the customer was created from (e.g., `LOYALTY`).               |
| `reference_id`           | string (nullable)  | External reference ID for third-party integrations.                  |
| `status`                 | boolean            | Whether the customer account is active.                              |
| `can_use_loyalty_system` | boolean            | Whether the customer is enrolled in the loyalty system.              |
| `is_verified`            | boolean            | Whether the customer's identity has been verified.                   |
| `created_at`             | string             | Timestamp when the customer was created (ISO 8601).                  |
| `updated_at`             | string             | Timestamp when the customer was last updated (ISO 8601).             |

## Notes

* **Filterable fields:** `name` (partial match), `phones` (searches across all phone numbers), `group_id` (exact match). Note: use `phones` (plural) — the singular `phone` field is not filterable.
* **Sortable fields:** `id`, `cid`, `group_id`, `name`, `email`, `address`, `created_at`, `updated_at`.
* The `search` query parameter is listed in some older references but is **not implemented** — use `filters` instead.