- Get a list of clients
Filter and sort the client base, returning meta.total_count and only the requested fields for one page. If fields is omitted, each row contains only id. This endpoint cannot return tags/categories, custom fields, birth date, loyalty card or comments; use the deprecated GET /clients/{location_id} for full profile pages or GET /client/{location_id}/{id} for one card.
Fields to return in each row. id is always included; without this property, only id is returned. Categories/tags and custom fields are unavailable here.
[ "id", "name", "phone", "last_visit_date" ]
What field to sort by
How the top-level filters are combined: AND (default, every filter must match) or OR (any filter matches)
Filters for searching the client base of the Location. Each item is either a condition (type and state) or a group (operation and nested filters, without type). Groups can be nested to build expressions such as (gender AND importance) OR quick_search. An unknown type or an invalid state returns 400.
Common state shapes:
- List:
{"value": [1, 2], "invert": false}.invert: trueexcludes the listed values. - Range:
{"from": 1, "to": 10}. Either bound can be omitted. - Date range:
{"from": "2026-01-01", "to": "2026-01-31"}. Dates useYYYY-MM-DDor a relative offset from today such as-30 days,0 days,+1 month(day,week,month,year, singular or plural). Date-time strings are rejected. - Boolean:
{"value": true}.
type | state | Matches clients |
|---|---|---|
id | List of client IDs | With these IDs |
quick_search | {"value": "text"} | Whose name, surname, patronymic, email or card number contains the text; a phone number also matches phone and additional_phone |
gender | List: 0 unknown, 1 male, 2 female | Of these genders |
importance | List: 0 none, 1 bronze, 2 silver, 3 gold | Of these importance levels |
category | List of client category (tag) IDs | Assigned at least one of the categories |
birthday | Date range shorter than one year | Whose birthday (month and day, year ignored) falls in the window; the window may cross the new year |
age | Range in full years | Of this age |
sold_amount | Range | Whose total sales amount in the Location is in the range |
deposit_balance | Range | Whose Client Account balance in the Location is in the range |
has_mobile_app | Boolean | With (or without) a push-enabled device for the Location's mobile app |
has_yplaces_app | Boolean | With (or without) the Altegio client app |
is_newsletter_allowed | Boolean | Who allowed (or did not allow) newsletters |
is_personal_data_processing_allowed | Boolean | Who allowed (or did not allow) personal data processing |
is_mass_notification_allowed | Boolean | Who can (or cannot) receive mass notifications |
is_push_notification_enabled | Boolean | With push notifications enabled (or disabled) |
sms_notification | Date range, optional invert | Who received an SMS notification from the Location in the window; invert: true returns clients who did not |
record | Object, see below | With Appointments matching all given conditions |
client | Object whose keys are filter types (for example gender, age, birthday) and values are their states | Matching all nested conditions |
sale | Object whose keys are any of the sale filter types below | Matching all nested sale conditions |
sale_abonement | Object with membership keys below | Who bought a Membership matching all nested conditions |
sale_certificate | Object with gift card keys below | Who bought a gift card matching all nested conditions |
sale_good | Object with product keys below | Who bought a Product matching all nested conditions |
record state keys (all optional, combined with AND): staff (list of Team Member IDs), service (list of Service IDs), service_category (list of Service Category IDs), status (list: 1 did not come, 2 pending, 3 arrived, 4 confirmed), created (date range of the Appointment date), records_count (range of matching Appointments), sold_amount (range with optional type: service_amount, the default, or paid_in_cash), and invert (true returns clients without such Appointments). Deleted Appointments are ignored.
Membership keys: abonement_types (list of Membership Type IDs), abonement_statuses (list: 1 not activated, 2 active, 3 expired, 4 used up), abonement_sale_date and abonement_expire_date (date ranges), abonement_is_frozen and abonement_is_used (booleans), abonement_balance (range of remaining visits).
Gift card keys: certificate_types (list of gift card type IDs), certificate_sale_date and certificate_expire_date (date ranges), certificate_balance (range), certificate_is_used (boolean).
Product keys: goods ({"good_ids": [...], "good_category_ids": [...]}; a category also matches its child categories) and good_sale_date (date range).
[ { "type": "record", "state": { … } }, { "type": "is_newsletter_allowed", "state": { … } }, { "operation": "OR", "filters": [ … ] } ]
- Mock serverhttps://developer.alteg.io/_mock/en/b2b-v1/openapi/locations/{location_id}/clients/search
- Productionhttps://api.alteg.io/api/v1/locations/{location_id}/clients/search
curl -i -X POST \
'https://developer.alteg.io/_mock/en/b2b-v1/openapi/locations/{location_id}/clients/search' \
-H 'Accept: string' \
-H 'Authorization: Bearer <YOUR_Bearer {PartnerToken}, User {UserToken}_HERE>' \
-H 'Content-Type: application/json' \
-d '{
"page": 1,
"page_size": 25,
"fields": [
"id",
"name",
"phone",
"last_visit_date"
],
"order_by": "last_visit_date",
"order_by_direction": "DESC",
"operation": "AND",
"filters": [
{
"type": "record",
"state": {
"status": {
"value": [
3
]
},
"created": {
"from": "-90 days",
"to": "0 days"
},
"records_count": {
"from": 2
}
}
},
{
"type": "is_newsletter_allowed",
"state": {
"value": true
}
},
{
"operation": "OR",
"filters": [
{
"type": "birthday",
"state": {
"from": "0 days",
"to": "+7 days"
}
},
{
"type": "sale_abonement",
"state": {
"abonement_statuses": {
"value": [
2
]
},
"abonement_expire_date": {
"from": "0 days",
"to": "+14 days"
}
}
}
]
}
]
}'OK
Array of objects with data
[ { "name": "James Smith", "id": 2 }, { "name": "Taylor Reed", "id": 3 }, { "name": "James Smith", "id": 1 } ]
{ "success": true, "data": [ { … }, { … }, { … } ], "meta": { "total_count": 908 } }