Skip to content

Get a list of clients

Request

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.

Security
BearerPartnerUser
Path
location_idnumberrequired

location ID

Headers
Acceptstringrequired

application/vnd.api.v2+json

Content-Typestringrequired

application/json

Authorizationstringrequired

Bearer partner_token, User user_token

Bodyapplication/jsonrequired
pagenumber

Page number

Example:1
page_sizenumber

The number of output lines per page. Maximum 200. (Default 25)

Example:25
fieldsArray of strings

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.

Items Enum:"id""name""surname""patronymic""phone""email""discount""first_visit_date""last_visit_date""sold_amount"
Example:
[ "id", "name", "phone", "last_visit_date" ]
order_bystring

What field to sort by

Enum:"id""name""phone""email""discount""first_visit_date""last_visit_date""sold_amount""visits_count"
Example:"last_visit_date"
order_by_directionstring

How to sort (ascending / descending)

Enum:"ASC""DESC"
Example:"DESC"
operationstring

How the top-level filters are combined: AND (default, every filter must match) or OR (any filter matches)

Enum:"AND""OR"
Example:"AND"
filtersArray of objects

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: true excludes the listed values.
  • Range: {"from": 1, "to": 10}. Either bound can be omitted.
  • Date range: {"from": "2026-01-01", "to": "2026-01-31"}. Dates use YYYY-MM-DD or 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}.
typestateMatches clients
idList of client IDsWith 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
genderList: 0 unknown, 1 male, 2 femaleOf these genders
importanceList: 0 none, 1 bronze, 2 silver, 3 goldOf these importance levels
categoryList of client category (tag) IDsAssigned at least one of the categories
birthdayDate range shorter than one yearWhose birthday (month and day, year ignored) falls in the window; the window may cross the new year
ageRange in full yearsOf this age
sold_amountRangeWhose total sales amount in the Location is in the range
deposit_balanceRangeWhose Client Account balance in the Location is in the range
has_mobile_appBooleanWith (or without) a push-enabled device for the Location's mobile app
has_yplaces_appBooleanWith (or without) the Altegio client app
is_newsletter_allowedBooleanWho allowed (or did not allow) newsletters
is_personal_data_processing_allowedBooleanWho allowed (or did not allow) personal data processing
is_mass_notification_allowedBooleanWho can (or cannot) receive mass notifications
is_push_notification_enabledBooleanWith push notifications enabled (or disabled)
sms_notificationDate range, optional invertWho received an SMS notification from the Location in the window; invert: true returns clients who did not
recordObject, see belowWith Appointments matching all given conditions
clientObject whose keys are filter types (for example gender, age, birthday) and values are their statesMatching all nested conditions
saleObject whose keys are any of the sale filter types belowMatching all nested sale conditions
sale_abonementObject with membership keys belowWho bought a Membership matching all nested conditions
sale_certificateObject with gift card keys belowWho bought a gift card matching all nested conditions
sale_goodObject with product keys belowWho 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).

Example:
[ { "type": "record", "state": { … } }, { "type": "is_newsletter_allowed", "state": { … } }, { "operation": "OR", "filters": [ … ] } ]
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"
              }
            }
          }
        ]
      }
    ]
  }'

Responses

OK

Bodyapplication/json
successboolean

Execution success status (true)

Example:true
dataArray of objects

Array of objects with data

Example:
[ { "name": "James Smith", "id": 2 }, { "name": "Taylor Reed", "id": 3 }, { "name": "James Smith", "id": 1 } ]
metaobject

Metadata (contains the number of clients found)

Example:
{ "total_count": 908 }
Response
{ "success": true, "data": [ { … }, { … }, { … } ], "meta": { "total_count": 908 } }