Skip to main content
This endpoint retrieves a list of all customers with support for pagination, filtering, and including related data.
There is no search parameter on this endpoint. To find customers by name or phone, use the filters parameter described below.

​
HTTP Request

GET https://integrations.clopos.com/open-api/v2/customers
This endpoint requires authentication. Include your JWT in the x-token header. See Authentication for how to obtain a token and Errors for error responses.

​
Query Parameters

​
page
integer
default:"1"
Page number for pagination (1-based).
​
limit
integer
default:"50"
Number of customers to return per page (1-999).
​
with[]
string
Include related data in the response. Supported values: group. You can include multiple with parameters.
​
filters
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

​
Request Examples

curl --location "https://integrations.clopos.com/open-api/v2/customers?page=1&limit=50" \
  -H "x-token: oauth_example_token" \

​
Response Example

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

FieldTypeDescription
idintegerUnique customer identifier.
cidstringUUID identifier for the customer.
venue_idintegerThe venue this customer belongs to.
group_idintegerThe ID of the customer group they belong to.
namestringCustomer’s full name.
emailstring (nullable)Customer’s email address.
phonestring (nullable)Primary phone number.
phonesarrayAdditional phone numbers.
addressstring (nullable)Customer’s address.
address_dataarrayStructured address entries with type, source, and formatted address.
descriptionstring (nullable)Additional notes about the customer.
discountnumberCustomer-level discount value.
spentnumberTotal amount spent by the customer.
total_discountnumberTotal discount amount received across all receipts.
total_bonusnumberTotal bonus amount used.
receipt_countintegerTotal number of receipts for the customer.
genderinteger (nullable)Gender: 1 = male, 2 = female, null = unspecified.
date_of_birthstring (nullable)Date of birth in YYYY-MM-DD format.
codestring (nullable)Customer code/identifier.
sourcestring (nullable)Where the customer was created from (e.g., LOYALTY).
reference_idstring (nullable)External reference ID for third-party integrations.
statusbooleanWhether the customer account is active.
can_use_loyalty_systembooleanWhether the customer is enrolled in the loyalty system.
is_verifiedbooleanWhether the customer’s identity has been verified.
created_atstringTimestamp when the customer was created (ISO 8601).
updated_atstringTimestamp 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.