👥 API: Клиенты

Управление профилями клиентов, атрибутами и историей изменений

💡 Основная концепция: Профили клиентов формируются автоматически на основе событий. Каждый уникальный user_id или anonymous_id создает отдельный профиль.

Базовые понятия

Идентификаторы клиентов

Тип ID Описание Пример
user_id Внешний ID из вашей системы (email, номер клиента, UUID) "user_12345", "customer@example.com"
anonymous_id ID неавторизованного пользователя (cookie, device ID) "abc-123-def"
id (Instant) Внутренний числовой ID в системе InstantBase 10042

Атрибуты клиентов

Атрибуты — это любая информация о клиенте: email, телефон, имя, город, подписка и т.д. Они могут быть:

Эндпоинты для работы с клиентами

1. Получение списка клиентов

GET /api/customers — получение списка клиентов с пагинацией, поиском и сортировкой.

Параметры запроса

Параметр Описание По умолчанию
page Номер страницы 1
limit Количество записей на странице 20
search Поиск по ID или UID —
sort_column Поле для сортировки last_seen
sort_direction Направление сортировки (asc или desc) desc

Допустимые поля для сортировки

Пример запроса

bash 
curl -X GET "https://api.instantbase.online/api/customers?page=1&limit=20&sort_column=last_seen&sort_direction=desc" \
  -H "Cookie: session_id=ваша_сессия"

Пример ответа

{
  "data": [
    {
      "id": 10042,
      "external_account_id": "user_12345",
      "first_seen": "2026-03-01 10:23:00",
      "last_seen_at": "2026-03-19 14:32:00",
      "events_count": 156,
      "ip": "192.168.1.1",
      "country": "Россия",
      "region": "Москва",
      "city": "Москва",
      "attributes": {
        "email": "user@example.com",
        "name": "Иван Петров",
        "phone": "+79001234567",
        "subscription_plan": "premium"
      },
      "email": "user@example.com"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  },
  "sort": {
    "column": "last_seen",
    "direction": "desc"
  }
}

2. Получение метрик клиентов

GET /api/customers/metrics?from=...&to=... — агрегированные метрики по клиентам за период.

Параметры запроса

Параметр Описание По умолчанию
from Начальная дата (YYYY-MM-DD) -30 дней
to Конечная дата (YYYY-MM-DD) сегодня

Пример ответа

{
  "success": true,
  "total_customers": 1250,
  "new_customers": 234,
  "activation_rate": 67.5,
  "avg_activity": 12.3,
  "total_change": 5.2,
  "new_change": 8.1,
  "activation_change": -2.3,
  "avg_change": 1.5,
  "period": {
    "from": "2026-03-01",
    "to": "2026-03-19"
  }
}
Поле Описание
total_customers Всего уникальных клиентов за период
new_customers Новые клиенты (первое событие в периоде)
activation_rate Процент новых клиентов, совершивших целевое действие
avg_activity Среднее количество событий на клиента

3. Получение доступных атрибутов

GET /api/customers/attributes — список всех атрибутов, которые можно отображать в таблице клиентов.

Пример ответа

{
  "success": true,
  "attributes": [
    {
      "id": 1,
      "name": "email",
      "value_type": "string",
      "display_name": "Email",
      "category": "Контакты",
      "format": null,
      "visible_in_customers": true
    },
    {
      "id": 2,
      "name": "phone",
      "value_type": "string",
      "display_name": "Телефон",
      "category": "Контакты",
      "format": null,
      "visible_in_customers": true
    },
    {
      "id": 3,
      "name": "subscription_plan",
      "value_type": "string",
      "display_name": "Тариф",
      "category": "Подписка",
      "format": null,
      "visible_in_customers": true
    }
  ]
}

4. История изменений атрибута

GET /api/customers/attribute-history?account_id=...&attribute_id=... — просмотр истории изменений конкретного атрибута клиента.

Параметры запроса

Параметр Описание
account_id ID клиента в системе InstantBase
attribute_id ID атрибута

Пример ответа

{
  "success": true,
  "account_id": 10042,
  "account_name": "user_12345",
  "attribute": {
    "id": 3,
    "name": "subscription_plan",
    "display_name": "Тариф",
    "value_type": "string"
  },
  "history": [
    {
      "created_at": "2026-03-19 10:23:00",
      "value": "premium",
      "is_current": true,
      "source_version": "1.2.0"
    },
    {
      "created_at": "2026-03-01 14:30:00",
      "value": "basic",
      "is_current": false,
      "source_version": "1.1.0"
    }
  ]
}

5. География пользователей

GET /api/geography?from=...&to=...&level=... — распределение пользователей по странам, регионам и городам.

Параметры запроса

Параметр Описание По умолчанию
from Начальная дата -30 дней
to Конечная дата сегодня
level Уровень детализации: country, region, city country

Пример ответа

[
  {
    "name": "Россия",
    "country_code": "RU",
    "users_count": 1250,
    "events_count": 15420
  },
  {
    "name": "США",
    "country_code": "US",
    "users_count": 450,
    "events_count": 5230
  }
]

Работа с атрибутами

Добавление атрибутов через события

Атрибуты передаются в поле attributes при отправке события:

json 
{
  "event": "signup",
  "user_id": "user_123",
  "attributes": {
    "email": "user@example.com",
    "name": "Иван Петров",
    "phone": "+79001234567",
    "birth_date": "1990-01-01",
    "city": "Москва",
    "subscription_plan": "premium",
    "preferred_language": "ru"
  }
}

Типы данных атрибутов

InstantBase автоматически определяет тип данных атрибута:

Тип данных Описание Пример
string Текстовое значение "Иван Петров"
integer Целое число 25
float Число с плавающей точкой 3.14
boolean Логическое значение true
date Дата (автоматически распознается) "1990-01-01"
json Сложные структуры {"key": "value"}

Обновление атрибутов

При отправке события с теми же именами атрибутов их значения обновляются. История изменений сохраняется.

// Первое событие
{
  "event": "user_updated",
  "user_id": "user_123",
  "attributes": {
    "subscription_plan": "basic"
  }
}

// Через месяц апгрейд
{
  "event": "user_updated",
  "user_id": "user_123",
  "attributes": {
    "subscription_plan": "premium"
  }
}

Системные атрибуты

Некоторые атрибуты имеют специальное значение и обрабатываются особым образом:

Атрибут Описание Применение
email Email пользователя Используется для уведомлений, отображается в интерфейсе
phone Телефон пользователя Для уведомлений и верификации
name Имя пользователя Отображается в интерфейсе

Метаданные атрибутов

Метаданные позволяют настроить отображение и поведение атрибутов:

Метаданные Описание Пример
attribute_display_name Отображаемое имя атрибута "Тариф"
attribute_category Категория для группировки "Подписка"
attribute_color Цвет для виджетов "#FF5733"
attribute_format Формат отображения currency, percent, date
attribute_visible_in_customers Показывать ли атрибут в таблице клиентов true

Пример передачи метаданных атрибута

{
  "event": "user_updated",
  "user_id": "user_123",
  "attributes": {
    "subscription_plan": "premium",
    "_metadata": {
      "subscription_plan": {
        "attribute_display_name": "Тариф",
        "attribute_category": "Подписка",
        "attribute_format": "string"
      }
    }
  }
}

Фильтрация и поиск

Поиск по клиентам

Параметр search позволяет искать:

Сортировка по пользовательским атрибутам

Можно сортировать по любому атрибуту, указав его имя в sort_column:

GET /api/customers?sort_column=email&sort_direction=asc

Геоданные

Информация о местоположении пользователей определяется автоматически по IP-адресу. Доступны следующие уровни детализации:

Уровень Описание
country Страна (по умолчанию, если пользователи распределены)
region Регион/область (автоматически, если >80% из одной страны)
city Город (автоматически, если >80% из одного региона)

Примеры использования

Создание профиля при регистрации

{
  "event": "signup",
  "user_id": "user_12345",
  "attributes": {
    "email": "user@example.com",
    "name": "Иван Петров",
    "phone": "+79001234567",
    "referral_source": "google_ads"
  }
}

Обновление профиля

{
  "event": "profile_updated",
  "user_id": "user_12345",
  "attributes": {
    "name": "Иван Иванов",
    "city": "Санкт-Петербург"
  }
}

Получение клиентов с определенным атрибутом

Для фильтрации по атрибутам используйте поиск или загрузите всех клиентов и фильтруйте на стороне клиента.

Коды ошибок

Код Описание Решение
400 Invalid date format Проверьте формат дат (YYYY-MM-DD)
400 Application not found Проверьте переданный app_id
401 Unauthorized Требуется авторизация через сессию
404 Customer not found Клиент с указанным ID не найден
500 Internal server error Повторите запрос позже

Рекомендации

  • Передавайте атрибуты при каждом событии — даже если они не меняются, это гарантирует актуальность данных
  • Используйте единый формат данных — например, всегда передавайте телефон в формате +79001234567
  • Не создавайте слишком много атрибутов — фокусируйтесь на действительно важных для бизнеса
  • Настраивайте метаданные атрибутов — это улучшает отображение в интерфейсе
  • Проверяйте историю изменений — это помогает отлаживать проблемы

Что дальше?

💰 Выручка

Аналитика по заказам и доходам

Перейти →

📈 Удержание

Когортный анализ и возвращаемость

Перейти →

Нужна помощь с профилями клиентов?

Напишите нам, и мы поможем настроить атрибуты

support@instantbase.online Telegram