Начало работы
API позволяет вашим системам (например, CRM или скриптам) обмениваться данными с сервисом Matomba без участия человека: получать заявки, управлять квизами и забирать аналитику. Для доступа нужен секретный ключ.
- Базовый адрес: https://rest.matomba.ru
- Адрес метода: /раздел или /раздел/{id}, например /quiz/30506. Разделы: deal, quiz, analytics.
- Формат: JSON, UTF-8. В GET-запросах параметры передаются в строке запроса, в POST, PUT и DELETE — JSON в теле.
- Авторизация: заголовок Authorization: Bearer ваш_ключ.
1. Доступ к API
API доступен при активной подписке на тарифах «Самозанятый», «Малый бизнес», «Бизнес», «Бизнес+», «Корпорация» и eLama. На тарифах «Тестовый» и «Старт», а также после окончания подписки любой запрос вернёт ошибку 402.
2. Где создать ключ
Откройте раздел «API» в личном кабинете и нажмите «Создать ключ». Укажите название (например, «Моя CRM») и отметьте права доступа, которые нужны вашей системе.
После создания на экране появится ключ вида matomba_xxxx_yyyy. Скопируйте его и сохраните в надёжном месте: повторно посмотреть ключ в кабинете нельзя, сервер хранит только его зашифрованную копию. Если ключ потерян, отзовите его и создайте новый.
3. Права доступа (scopes)
Право на чтение (.read) нужно для GET-запросов, право на запись (.write) — для POST, PUT и DELETE. Давайте ключу только те права, которые действительно нужны: если ключ утечёт, ущерб будет меньше.
- deal.read — получение заявок.
- quiz.read — просмотр квизов и их структуры.
- quiz.write — создание, изменение, копирование и удаление квизов.
- analytics.read — получение аналитики по квизам.
- analytics.write — очистка аналитики квиза.
4. Как передать ключ в запросе
curl -sS "https://rest.matomba.ru/quiz" \
-H "Authorization: Bearer matomba_a1b2c3d4e5f60718_9f8e7d6c5b4a3210ffeeddccbbaa99887766554433221100" \
-H "Accept: application/json"Никогда не публикуйте ключ в открытых репозиториях и не используйте его на стороне клиента (в браузере или мобильном приложении) — там его может увидеть любой. Запросы к API выполняйте только со своего сервера.
5. Ограничения
Не более 3 запросов в секунду с одного ключа. При превышении сервер вернёт ошибку 429. В этом случае подождите секунду и повторите запрос.
6. Ошибки
При ошибке сервер возвращает HTTP-код и JSON-объект error:
{
"error": {
"code": "number · HTTP-код ошибки",
"message": "string · текст ошибки"
}
}Коды ошибок:
- 400 — неверный запрос: например, в теле нет объекта app.
- 401 — ключ не передан, указан неверно или отозван.
- 402 — API недоступен на вашем тарифе или подписка закончилась.
- 403 — у ключа нет нужного права, достигнут лимит квизов на тарифе или запрошенный период аналитики недоступен.
- 404 — метод или объект не найден, либо по запросу нет данных.
- 409 — адрес (url) или домен квиза уже занят другим квизом либо указан неверно.
- 422 — неверный формат даты, дата в будущем или конец периода раньше начала.
- 429 — превышен лимит запросов.
- 500 — внутренняя ошибка: не удалось сохранить или скопировать квиз. Повторите запрос позже.
7. Как читать описания ответов
В описаниях ниже вместо реальных значений указано тип · что означает поле. Типы:
- number — число.
- string — строка.
- flag — признак «включено/выключено»: 1 — да, пустая строка "" — нет.
- datetime — дата и время YYYY-MM-DD HH:MM:SS (московское время); date — только дата YYYY-MM-DD.
- object / array — вложенный объект или массив.
- Варианты значений перечислены через |, например left | right.
- Запись open|start|form|finish в ключе означает несколько однотипных полей с одинаковым описанием.
- Поле _ — пояснение в документации, в реальном ответе его нет.
Вопросы, варианты ответов, результаты и другие элементы квиза имеют числовые ID. Ими элементы ссылаются друг на друга: в условиях показа, формулах и аналитике.
8. Изображения
Картинки в ответах передаются ключами — именами файлов с расширением (например, 9404bdf1240801d0d8b131c72f4a7f2c.webp). Чтобы получить ссылку на файл, добавьте ключ к базовому адресу:
https://cdn.matomba.ru/{key}Если в поле уже указан внешний URL (начинается с http), используйте его как есть.
Заявки
Список заявок
GET /dealВозвращает заявки от новых к старым, по 100 на страницу. Право: deal.read.
Параметры запроса
- app — ID квизов через запятую. Без параметра — заявки по всем квизам.
- date_start — заявки, созданные начиная с этого момента: YYYY-MM-DD или YYYY-MM-DD HH:MM:SS.
- date_end — заявки по этот день включительно: YYYY-MM-DD. Время, если передано, не учитывается.
- page — номер страницы, по умолчанию 1.
GET /deal?app=30506,30507&date_start=2026-11-01&date_end=2026-11-16&page=2Если по фильтрам ничего не найдено или страница за пределами списка, вернётся ошибка 404.
Структура ответа
{
"meta": {
"total": "number · всего заявок по заданным фильтрам",
"page": "number · номер текущей страницы",
"on_page": "number · сколько заявок на этой странице",
"per_page": "number · максимум заявок на странице (всегда 100)"
},
"data": [
{
"id": "number · ID заявки",
"user": "number · ID владельца аккаунта",
"app": "number · ID квиза, из которого пришла заявка",
"ab": "number | null · ID A/B-варианта квиза (null — основной вариант)",
"name": "string · имя клиента",
"mail": "string · email клиента",
"phone": "string · телефон: только цифры, с кодом страны",
"social": "object · контакты в мессенджерах: ключ — мессенджер (telegram, whatsapp, viber …), значение — контакт",
"more": "string · значение своего поля формы (field_default)",
"cmt": "string · комментарий к заявке",
"utm": "object · UTM-метки визита: utm_source, utm_medium, utm_campaign, utm_content, utm_term, utm_referer",
"query": "object · все GET-параметры страницы, на которой прошли квиз",
"analytics": "object · идентификаторы рекламы и аналитики: yclid (клик Яндекс Директа), _ym_uid (посетитель Яндекс Метрики) и др.",
"ip": "string · IP-адрес клиента",
"referer": "string · страница, с которой клиент пришёл",
"open": "datetime | null · когда заявку открыли в кабинете (null — ещё не просмотрена)",
"agree": [
"number · ID согласий, которые отметил клиент (quiz_feedback.politics[].id)"
],
"timeadd": "datetime · дата и время заявки",
"status": "number · статус заявки (0 — новая)",
"body": {
"cart": [
{
"_": "Результаты квиза, которые получил или выбрал клиент",
"id": "number · ID результата (quiz_result.id)",
"name": "string · название результата",
"about": "string · описание результата",
"cost": "number · цена",
"quantity": "number · количество",
"images": [
"string · ключи картинок (см. раздел «Изображения»)"
]
}
],
"answers": [
"ответы клиента на вопросы квиза"
],
"service": "string · выбранная услуга или подарок",
"currency": "string · валюта (RUB, USD …)",
"discount": "number · размер скидки, которую получил клиент",
"discount_type": "string · тип скидки (например, up_percent — в процентах)"
}
}
]
}Одна заявка
GET /deal/{id}Возвращает заявку по её ID. Право: deal.read.
Структура ответа
{
"data": "object · одна заявка; поля как у элемента data[] в GET /deal"
}Квизы
Список квизов
GET /quizВозвращает краткую информацию обо всех квизах аккаунта, кроме удалённых и заблокированных: и включённых, и выключенных. Сортировка — от новых к старым, пагинации нет. Если квизов нет, вернётся 404. Право: quiz.read.
Структура ответа
{
"data": {
"apps": [
{
"id": "number · ID квиза",
"modules": "string · тип: quiz (квиз) | www (сайт)",
"hash": "string · хеш квиза",
"url": "string · публичный идентификатор квиза в ссылке",
"domain": "string | null · свой домен, если подключён",
"name": "string · название квиза",
"project_name": "string · название проекта",
"timeadd": "datetime · дата создания",
"timemod": "datetime · дата последнего изменения",
"analytics_end": "date | null · до какого числа оплачена расширенная аналитика"
}
]
},
"meta": {
"count": "number · сколько квизов в списке"
}
}Один квиз
GET /quiz/{id}Возвращает полную структуру квиза: настройки, оформление, вопросы, результаты, формы и финальные страницы. Массивы quiz_* приходят внутри app, и только если в них есть элементы. Право: quiz.read.
Структура ответа
{
"data": {
"app": {
"id": "number · ID квиза",
"hash": "string · внутренний хеш квиза",
"modules": "string · тип приложения: quiz (квиз) | www (сайт)",
"url": "string · публичный идентификатор (slug) квиза в ссылке",
"domain": "string · свой домен, если подключён (пусто — нет)",
"domain_open": "flag · свой домен активирован",
"vk_group_id": "number · ID группы ВКонтакте для интеграции (0 — нет)",
"user": "number · ID владельца",
"user_created": "number · ID пользователя, создавшего квиз",
"project_name": "string · название проекта (папки проектов)",
"name": "string · название квиза в кабинете",
"seo": {
"title": "string · заголовок страницы (тег title)",
"description": "string · meta description",
"favicon": "string · файл фавиконки",
"social": {
"title": "string · заголовок для превью в соцсетях (og:title)",
"description": "string · описание для превью (og:description)",
"preview": "string · картинка для превью (og:image)"
}
},
"whitelabel": "flag · скрыть брендинг сервиса",
"whitelabel_link": "string · своя ссылка вместо брендинга",
"language": "string · язык интерфейса квиза (ru, en …)",
"currency": "string · валюта (rub, usd …)",
"timeadd": "datetime · дата создания (YYYY-MM-DD HH:MM:SS)",
"timemod": "datetime · дата последнего изменения",
"is_active": "number · 1 — квиз включён, 0 — выключен",
"tags": "string · теги",
"folder": "number · ID папки в кабинете (0 — корень)",
"robots": "flag · разрешить индексацию поисковиками",
"analytics_end": "date | null · до какого числа оплачена расширенная аналитика",
"design": "number · ID шаблона дизайна (0 — по умолчанию)",
"pages": {
"view": "flag · включён режим «страница» (лендинг из блоков)",
"button": {
"text": "string · текст кнопки старта",
"type": "string · тип кнопки (button)"
},
"contain": [
"Массив блоков страницы. У каждого есть id и module, остальные поля зависят от module:",
{
"id": "number",
"module": "quiz-pages-header",
"type": "string · logo | text",
"head": "string · заголовок",
"text": "string · подзаголовок",
"image": "string · файл логотипа",
"position": "string · left | center | right"
},
{
"id": "number",
"module": "quiz-pages-text",
"tag": "string · HTML-тег: p | h1 | h2 …",
"text": "string · текст",
"position": "string · выравнивание"
},
{
"id": "number",
"module": "quiz-pages-image",
"type": "string · vertical | horizontal",
"items": [
"string · файлы картинок"
],
"slideshow": "flag · показывать слайдером"
},
{
"id": "number",
"module": "quiz-pages-link",
"type": "string · button",
"head": "string · заголовок",
"text": "string · текст кнопки",
"link": "string · URL",
"size": "string · small | medium | big",
"color": "string · цвет текста #hex",
"background": "string · цвет фона #hex",
"image": "string · иконка"
},
{
"id": "number",
"module": "quiz-pages-video",
"type": "string · vertical | horizontal",
"video": "string · ссылка на видео",
"image": "string · обложка"
},
{
"id": "number",
"module": "quiz-pages-gift",
"position": "string · выравнивание блока подарков"
},
{
"id": "number",
"module": "quiz-pages-footer",
"name": "string · название компании",
"phone": "string · телефон",
"menu": [
"ссылки меню"
],
"social": "string · соцсети",
"details": "string · реквизиты",
"disclaimer": "string · дисклеймер",
"position": "string · выравнивание"
}
]
},
"landing": {
"view": "flag · показывать стартовую страницу",
"style": "string · расположение картинки: left | right | center | background",
"head": "string · главный заголовок",
"text": "string · подзаголовок / выгода для клиента",
"bonus": "string · плашка с бонусом над заголовком",
"button": "string · текст кнопки старта",
"static_button": "flag · закрепить кнопку при скролле",
"slogan": "string · слоган компании",
"company": "string · название компании",
"phone": "string · телефон в шапке",
"logo": "string · файл логотипа",
"preview": "string · файл картинки стартовой страницы",
"image_phone": "string · размер картинки на мобильных: BIG | SMALL",
"video": "string · ссылка на видео",
"video_view": "flag · показывать видео вместо картинки",
"socials": "string · ссылки на соцсети",
"link": [
"дополнительные ссылки"
],
"divider_off": "flag · скрыть разделитель",
"header": {
"size": "string · размер заголовка: small | medium | large",
"weight": "number · насыщенность шрифта (400–800)"
},
"background": {
"color": "string · цвет текста #hex",
"background": "string · цвет затемнения #hex",
"opacity": "number · прозрачность затемнения, %"
}
},
"showcase": {
"view": "flag · показывать витрину результатов",
"position": "string · где показывать: before (до формы) | after (после)",
"head": "string · заголовок витрины",
"text": "string · подзаголовок",
"bonus": "string · заголовок блока бонусов",
"button": "string · текст кнопки",
"help": "flag · показывать подсказку",
"share": "flag · кнопки «поделиться»",
"repeat": "flag · кнопка «пройти заново»",
"raiting": "flag · показывать рейтинг результатов"
},
"manager": {
"name": "string · имя консультанта, который «ведёт» по квизу",
"about": "string · должность",
"avatar": "string · файл аватара"
},
"setting": {
"font": "string · шрифт (fira-sans …)",
"color": "string · основной цвет текста #hex",
"background": "string · фон квиза #hex",
"body": "string · фон страницы вокруг квиза #hex",
"border": "string · цвет рамок #hex",
"radius": "number · скругление углов, px",
"second_color": "string · цвет текста второстепенных блоков #hex",
"second_background": "string · фон второстепенных блоков #hex",
"button_color": "string · цвет текста кнопок #hex",
"button_background": "string · цвет кнопок #hex",
"button_fill": "flag · кнопки с заливкой (иначе контур)",
"rule_color": "string · цвет текста плашки бонуса #hex",
"rule_background": "string · фон плашки бонуса #hex",
"close_color": "string · цвет крестика закрытия #hex",
"progress_bar": "flag · показывать прогресс-бар",
"autonext": "flag · авто-переход к следующему вопросу после ответа",
"language": "string · язык",
"valute": "string · валюта",
"politics": "string · URL политики конфиденциальности",
"masked": "flag · маска ввода телефона",
"mask": [
"ru",
"kz",
"by",
"… ещё ~220 кодов стран ISO 3166-1 alpha-2, доступных в маске телефона"
],
"field_name": "string · подпись поля «имя»",
"field_phone": "string · подпись поля «телефон»",
"field_mail": "string · подпись поля «email»",
"field_default": "string · подпись своего поля",
"placeholder_name": "string · плейсхолдер поля «имя»",
"placeholder_phone": "string · плейсхолдер поля «телефон»",
"placeholder_mail": "string · плейсхолдер поля «email»",
"placeholder_default": "string · плейсхолдер своего поля",
"important_name": "flag · поле «имя» обязательное",
"important_phone": "flag · поле «телефон» обязательное",
"important_mail": "flag · поле «email» обязательное",
"important_default": "flag · своё поле обязательное",
"randomize": {
"view": "flag · перемешивать вопросы",
"count": "number · сколько вопросов показывать (0 — все)",
"order": "number · порядок"
},
"duplicate": "string · защита от повторных заявок: none | phone | mail",
"utm": "flag · передавать UTM-метки",
"cookie": "flag · баннер cookie",
"memory": "flag · запоминать прогресс",
"once": "flag · пройти можно только один раз",
"request": "flag · служебный флаг отправки"
},
"dynamic": {
"view": "flag · включены динамические подстановки (по UTM/параметрам)",
"items": [
"правила подстановки"
]
},
"discount": {
"view": "flag · показывать бонус-скидку",
"head": "string · заголовок блока",
"type": "string · fixed (фиксированная) | grow (растёт с каждым ответом)",
"number": "string · currency (в валюте) | percent (в процентах)",
"count": "number · размер скидки"
},
"presents": {
"view": "flag · показывать подарки",
"step": "string · когда показывать: all (на всех шагах) | finish",
"style": "string · вид карточек: rectangle | circle",
"items": [
{
"id": "number · ID подарка",
"name": "string · название подарка",
"preview": "string · картинка",
"file": "string · прикреплённый файл (выдаётся после заявки)",
"href": "string · ссылка на подарок",
"color": "string · цвет текста #hex",
"background": "string · цвет фона #hex",
"opacity": "number · прозрачность фона, %"
}
]
},
"widjet": {
"fontFamily": "string · шрифт виджетов",
"popup": {
"opacity": "number · затемнение фона попапа",
"auto": {
"view": "flag · авто-открытие квиза",
"timeout": "number · через сколько секунд открыть",
"exit": "flag · открывать при попытке уйти со страницы",
"regular": "flag · открывать при каждом визите",
"web": "flag · на десктопе",
"phone": "flag · на мобильных",
"pages": [
"URL страниц, где работает"
],
"exclude": "string · URL-исключения"
},
"banner": {
"view": "flag · баннер-приглашение на сайте",
"head": "string · заголовок баннера",
"text": "string · текст баннера",
"position_x": "string · left | right",
"position_y": "string · top | bottom",
"full_width": "flag · на всю ширину",
"color": "string · цвет текста #hex",
"background": "string · цвет фона #hex",
"round": "flag · скругление",
"shadow": "flag · тень",
"blick": "flag · анимация блика",
"web": "flag · на десктопе",
"phone": "flag · на мобильных",
"pages": [
"URL страниц"
],
"exclude": "string · URL-исключения"
},
"button": {
"view": "flag · плавающая кнопка открытия квиза",
"text": "string · текст кнопки (mtext — для мобильных)",
"position": "string · left | right",
"fill": "flag · с заливкой",
"color": "string · цвет текста #hex",
"background": "string · цвет кнопки #hex",
"round": "flag",
"shadow": "flag",
"blick": "flag",
"web": "flag",
"phone": "flag",
"pages": [
"URL страниц"
],
"exclude": "string",
"mtop|mright|mbottom|mleft": "number · отступы на мобильных, px",
"ptop|pright|pbottom|pleft": "number · отступы на планшете, px",
"wtop|wright|wbottom|wleft": "number · отступы на десктопе, px"
}
},
"iframe": {
"button": "flag · встраивать как кнопку (иначе сразу квиз)",
"text": "string · текст кнопки",
"width": "number · ширина, px",
"height": "number · высота, px",
"weight": "number · насыщенность шрифта",
"fill": "flag",
"color": "string #hex",
"background": "string #hex",
"round": "flag",
"shadow": "flag",
"blick": "flag",
"phone": "flag"
},
"consultant": {
"view": "flag · виджет-«консультант» в углу экрана",
"text": "string · текст",
"position": "string · left | right",
"x": "number · смещение по X, px",
"y": "number · смещение по Y, px",
"delay": "number · задержка появления, сек",
"auto_open": "flag · раскрывать автоматически",
"color": "string #hex",
"background": "string #hex",
"round": "flag",
"shadow": "flag",
"blick": "flag",
"web": "flag",
"phone": "flag",
"pages": [
"URL страниц"
],
"exclude": "string"
}
},
"languages": [
"доступные переводы квиза"
],
"allowed_domain": [
"домены, где разрешено встраивание"
],
"is_test": "flag · режим теста (с правильными ответами и баллами)",
"is_memory": "flag · запоминать прогресс прохождения",
"is_once": "flag · одно прохождение на пользователя",
"is_defender": "flag · защита от спама",
"is_verify": "flag · подтверждение телефона по SMS",
"is_captcha": "flag · капча в форме",
"is_cookie": "flag · показывать согласие на cookie",
"is_autonext": "flag · авто-переход к следующему вопросу",
"is_get_utm": "flag · сохранять UTM-метки в заявку",
"is_get_contact": "flag · подставлять известные контакты",
"deduplicate": "string · дедупликация заявок: none | phone | mail",
"widjet_delay": "number · задержка загрузки виджета",
"widget_backdrop": "flag · затемнение фона под виджетом",
"widget_mobile_fullsize": "flag · виджет на весь экран на мобильных",
"widget_web_fullsize": "flag · виджет на весь экран на десктопе",
"widget_session": "flag · не показывать повторно в рамках сессии",
"tg_data": "string · настройки Telegram-бота",
"vk_data": "string · настройки ВКонтакте",
"quiz_ab": [
{
"_": "A/B-варианты квиза. Каждый вариант — полная копия контента со своими правками. Массив приходит, только если варианты есть.",
"id": "number · ID варианта",
"quiz": "number · ID квиза",
"name": "string · название варианта",
"view": "flag · вариант участвует в тесте",
"orderlist": "number · порядок варианта",
"landing": "object · как app.landing",
"showcase": "object · как app.showcase",
"questions": "array · как app.quiz_question",
"results": "array · как app.quiz_result",
"feedback": "array · как app.quiz_feedback",
"finish": "array · как app.quiz_finish",
"manager": "object · как app.manager",
"discount": "object · как app.discount",
"presents": "object · как app.presents",
"setting": "object · как app.setting"
}
],
"quiz_question": [
{
"id": "number · ID вопроса (на него ссылаются условия и формулы как #ID)",
"quiz": "number · ID квиза",
"orderlist": "number · порядковый номер вопроса",
"view": "flag · вопрос включён",
"type": "string · тип вопроса: list (варианты-чекбоксы) | card (карточки с картинками) | preview (варианты + большая картинка) | input (поле ввода) | multiinput (несколько полей) | range (ползунок) | select (выпадающий список) | date (дата) | file (загрузка файлов) | rank (рейтинг/шкала) | page (инфо-страница без ответа)",
"name": "string · текст вопроса",
"content": "string · текст (для type=page)",
"hint": "string · подсказка от консультанта",
"hint_mobile_view": "flag · показывать подсказку на мобильных",
"preview": "string · картинка вопроса (для type=preview)",
"video": "string · ссылка на видео",
"background": "string · фон вопроса",
"progress": "flag · скрыть прогресс-бар на этом вопросе",
"design": {
"align": "string · выравнивание: left | center",
"bold": "flag · жирный текст",
"color": "string · цвет текста #hex",
"element": "string · цвет элементов #hex",
"background": "string · цвет затемнения #hex",
"opacity": "number · прозрачность затемнения, %"
},
"multiple": "flag · можно выбрать несколько вариантов",
"multiple_limit": "number · максимум выбранных вариантов",
"optional": "flag · вопрос можно пропустить",
"reply": "flag · есть поле «свой ответ»",
"answer_text": "flag · показывать подписи у вариантов",
"placeholder": "string · плейсхолдер поля ввода / «своего ответа» / селекта",
"input_format": "string · формат поля (input): text | number | phone | email",
"multiinput_format": "string · формат полей (multiinput): text | number",
"ask_format": "string · формат вариантов: image | emoji",
"ask_image": "string · размер картинок: SMALL | MEDIUM | BIG",
"ask_wrap": "string · обрезка картинок: WRAP (вписать) | COVER (заполнить)",
"ask_multiplication": "flag · перемножать баллы вариантов",
"range_min": "number · минимум ползунка",
"range_max": "number · максимум ползунка",
"range_step": "number · шаг ползунка",
"range_default_min": "number · стартовое значение (левый бегунок)",
"range_default_max": "number · стартовое значение (правый бегунок)",
"span": "flag · range: диапазон из двух бегунков (иначе один)",
"rank_max": "number · rank: количество делений шкалы",
"rank_min_name": "string · rank: подпись минимума",
"rank_max_name": "string · rank: подпись максимума",
"calendar": "flag · date: показывать календарь",
"data_span": "flag · date: выбор периода (две даты)",
"data_time": "flag · date: с выбором времени",
"multiple_file": "flag · file: несколько файлов",
"map": "string · координаты/карта (зарезервировано)",
"ask": [
{
"_": "Варианты ответа (для list, card, preview, select)",
"id": "number · ID варианта (используется в условиях)",
"name": "string · текст варианта",
"about": "string · описание под вариантом",
"preview": "string · картинка варианта",
"emoji": "string · эмодзи вместо картинки",
"digit": "number · числовое значение варианта (участвует в формулах цены)",
"point": "number · баллы за вариант (для теста/скоринга)",
"truth": "flag · правильный ответ (режим теста)",
"is_default": "flag · выбран по умолчанию"
}
],
"inputs": [
{
"_": "Поля (для multiinput)",
"id": "number · ID поля",
"name": "string · подпись поля",
"placeholder": "string · плейсхолдер"
}
],
"conditions_view": "flag · 1 — показывать вопрос при выполнении условий, 0 — скрывать",
"conditions_all": "flag · 1 — должны выполниться все условия (И), иначе любое (ИЛИ)",
"conditions": [
"Условия показа. Формат зависит от типа вопроса, на который ссылается условие:",
{
"_": "по выбранным вариантам",
"question": "number · ID вопроса",
"ask": [
"number · ID вариантов"
],
"type": "string · or (любой из) | and (все)",
"more": "flag · допускаются и другие выбранные варианты"
},
{
"_": "по тексту ответа",
"question": "number · ID вопроса с полем ввода",
"value": "string · искомая фраза",
"include": "flag · 1 — содержит, 0 — не содержит"
},
{
"_": "по числовому ответу (range, rank)",
"question": "number · ID вопроса",
"min": "number · от",
"max": "number · до",
"include": "flag · 1 — внутри диапазона, 0 — вне"
}
]
}
],
"quiz_result": [
{
"id": "number · ID результата",
"quiz": "number · ID квиза",
"orderlist": "number · порядок",
"view": "flag · результат включён",
"name": "string · название результата",
"about": "string · описание; #ID_вопроса подставляет ответ пользователя на этот вопрос",
"images": [
"string · файлы картинок"
],
"video": "string · ссылка на видео",
"button": "string · текст кнопки",
"link": "string · ссылка кнопки",
"redirect": "string · URL для автоматического редиректа",
"finish": "number · ID финальной страницы, которую показать",
"cost_type": "string · как показывать цену: equally (=) | from (от) | to (до)",
"cost": "number · цена",
"formula": "string · формула расчёта цены, #ID — значение ответа (напр. #1792762331329*22+1)",
"discount": "number · скидка",
"discount_type": "string · quanity (в валюте) | percent (в процентах)",
"stock": "number · старая цена (зачёркнутая)",
"amount": "number · количество",
"instock": "flag · в наличии",
"null_sell": "flag · скрывать цену, если она равна 0",
"onilne_pay": "flag · онлайн-оплата результата",
"score_min": "number · показывать при баллах от",
"score_max": "number · показывать при баллах до",
"conditions_view": "flag · как у вопроса",
"conditions_all": "flag · как у вопроса",
"conditions": [
"условия, формат как у quiz_question.conditions"
]
}
],
"quiz_feedback": [
{
"id": "number · ID формы (0 — основная форма)",
"quiz": "number · ID квиза",
"orderlist": "number · порядок (шаг формы)",
"view": "flag · форма включена",
"name": "string · техническое название",
"prehead": "string · надзаголовок",
"head": "string · заголовок формы",
"text": "string · текст под заголовком",
"button": "string · текст кнопки отправки",
"fields": [
"string · поля формы: name | phone | mail | default (своё поле) | telegram | telegram_login | whatsapp | viber | vkontakte | max | messenger | facebook | instagram | discord | namesocial | phonenumber"
],
"messenger": "string · текст-разделитель «или мессенджер»",
"messenger_head": "string · заголовок экрана выбора мессенджера",
"messenger_button": "string · кнопка на экране мессенджера",
"messenger_back": "string · ссылка «вернуться к контактам»",
"agree": "flag · чекбокс согласия с политикой",
"politics": [
{
"id": "number · ID согласия",
"name": "string · название",
"about": "string · текст чекбокса",
"link": "string · ссылка на документ",
"is_default": "flag · отмечен по умолчанию",
"is_important": "flag · обязателен для отправки"
}
],
"progress": "flag · показывать прогресс-бар",
"js": "string · JS-код, выполняемый после отправки (цели, пиксели)",
"score_min": "number · показывать при баллах от",
"score_max": "number · показывать при баллах до",
"conditions_view": "flag",
"conditions_all": "flag",
"conditions": [
"условия, формат как у quiz_question.conditions"
]
}
],
"quiz_finish": [
{
"id": "number · ID финальной страницы (0 — основная)",
"quiz": "number · ID квиза",
"orderlist": "number · порядок",
"view": "flag · включена",
"name": "string · техническое название",
"head": "string · заголовок «спасибо»",
"text": "string · текст",
"bonus": "string · заголовок блока бонусов",
"style": "string · расположение картинки: left | right | center",
"preview": "string · картинка",
"video": "string · ссылка на видео",
"video_view": "flag · видео вместо картинки",
"button": "string · текст кнопки",
"button_link": "string · ссылка кнопки",
"link": "string · URL редиректа",
"timeout": "number · через сколько секунд редирект",
"social": "string · ссылки на соцсети, каждая с новой строки (\\n)",
"background": {
"color": "string · цвет текста #hex",
"background": "string · цвет затемнения #hex",
"opacity": "number · прозрачность, %"
},
"score_min": "number",
"score_max": "number",
"conditions_view": "flag",
"conditions_all": "flag",
"conditions": [
"условия, формат как у quiz_question.conditions"
]
}
]
}
}
}Создание квиза
POST /quizСоздаёт новый квиз. Право: quiz.write. Количество квизов ограничено тарифом; при достижении лимита вернётся 403.
Тело запроса
{
"app": "object · поля квиза, структура как в GET /quiz/{id}, но без вложенных массивов quiz_*. Обязателен и не может быть пустым",
"quiz_question": "array · вопросы",
"quiz_result": "array · результаты",
"quiz_feedback": "array · формы контактов",
"quiz_finish": "array · финальные страницы",
"quiz_ab": "array · A/B-варианты"
}Обратите внимание: в ответе GET /quiz/{id} массивы quiz_* лежат внутри app, а при создании их нужно передавать на верхнем уровне, рядом с app. Чтобы создать квиз по образцу существующего, получите его структуру, перенесите массивы quiz_* на верхний уровень и отправьте.
- Поля id, timeadd, timemod, analytics_end в app игнорируются; user, modules и hash сервер заполнит сам.
- url — необязательный: если не передан, совпадёт с hash. Должен быть уникальным, иначе 409.
- domain — необязательный: домен второго или третьего уровня, не занятый другим квизом.
- Порядок элементов в массивах задаёт их порядок в квизе.
- Сохраняйте id вопросов, вариантов ответа и результатов: на них ссылаются условия показа и формулы. Элементы без id получат новый случайный ID, и ссылки на них перестанут работать.
Структура ответа
{
"data": {
"id": "number · ID созданного квиза",
"hash": "string · хеш квиза"
}
}Изменение квиза
PUT /quiz/{id}Изменяет существующий квиз. Тело запроса — как при создании. Право: quiz.write.
- app — передавайте только поля, которые нужно изменить. Объект обязателен и не может быть пустым, даже если меняются только вопросы. Поля id, user, user_created, modules, hash, analytics_end, timeadd и timemod изменить нельзя — они игнорируются.
- Массивы quiz_* заменяются целиком: элементы с существующими id обновляются, новые добавляются, а элементы, которых нет в переданном массиве, удаляются.
- Если массив не передан, он не меняется. Пустой массив [] удаляет все элементы.
Структура ответа
{
"data": {
"id": "number · ID изменённого квиза",
"hash": "string · хеш квиза"
}
}Копирование квиза
POST /quiz/{id}Создаёт полную копию квиза с указанным ID вместе с вопросами, результатами, формами и A/B-вариантами. Тело запроса не нужно. У копии новые id, hash и url, свой домен не подключён. Копия учитывается в лимите квизов тарифа. Право: quiz.write.
Структура ответа
{
"data": {
"id": "number · ID копии",
"hash": "string · хеш копии",
"url": "string · публичный идентификатор копии (совпадает с hash)"
}
}Удаление квиза
DELETE /quiz/{id}Квиз перестаёт работать и возвращаться через API, свой домен отвязывается. Заявки по квизу сохраняются. Право: quiz.write.
Структура ответа
{
"data": {
"id": "number · ID удалённого квиза"
}
}Аналитика
Аналитика квиза
GET /analytics/{id}Возвращает статистику по квизу за день или период. Право: analytics.read.
Параметры запроса
- start — начало периода: YYYY-MM-DD или YYYYMMDD. Без параметра — отчёт за сегодня.
- end — конец периода в том же формате. Без параметра (или если совпадает с start) — отчёт за один день start.
- version — ID A/B-варианта, чтобы получить данные только по нему.
GET /analytics/30506?start=2026-10-17&end=2026-11-16Даты в будущем, даты в неверном формате и конец периода раньше начала вернут 422. Если за период нет данных, вернётся пустой data и meta.period.
Доступные периоды
Глубина аналитики зависит от тарифа. Можно запросить любой день или период, если его начало не раньше, чем:
- 7 дней назад — «Самозанятый»;
- 30 дней назад — «Малый бизнес»;
- 90 дней назад — «Бизнес»;
- 180 дней назад — «Бизнес+»;
- 360 дней назад — «Корпорация» и eLama.
Если для квиза оплачена детальная аналитика (analytics_end ещё не наступил), ограничения по глубине нет. Более ранние даты без оплаченной аналитики вернут 403.
Как читать отчёт
Основа отчёта — воронка из четырёх этапов: open (открыли квиз), start (начали), form (дошли до формы), finish (отправили заявку). Большинство разделов показывают эту воронку в разных разрезах: по меткам, устройствам, времени, A/B-вариантам. В полях event_id указан ID элемента квиза: вопроса, формы, результата или финальной страницы.
Структура ответа
{
"data": {
"stats": {
"open": "number · сколько раз открыли квиз",
"start": "number · сколько раз начали проходить",
"form": "number · сколько раз дошли до формы контактов",
"finish": "number · сколько раз отправили заявку"
},
"time_spent": "number · среднее время прохождения, сек",
"uniques": {
"_": "Этапы воронки по уникальным посетителям",
"open|start|form|finish": "number · уникальные посетители на каждом этапе",
"unique_clients": "number · уникальных клиентов, оставивших заявку",
"repeat_finish": "number · повторных заявок",
"step": "number · средний номер шага, до которого доходили посетители"
},
"previous": {
"_": "Те же показатели за предыдущий период такой же длины — для сравнения",
"open|start|form|finish": "number | null · воронка",
"time_spent": "number · среднее время прохождения, сек",
"uniques": "object | null · уникальные посетители, как в data.uniques"
},
"asked": [
{
"_": "До 1500 самых частых слов из ответов в полях ввода",
"word": "string · слово",
"asked": "number · сколько раз встретилось"
}
],
"utm": [
{
"utm": "string · хеш набора UTM-меток (расшифровка — в utm_v)",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"utm_v": [
{
"utm": "string · хеш набора",
"utm_source|utm_medium|utm_campaign|utm_content|utm_term": "string · значения меток"
}
],
"browser": [
{
"browser": "string · браузер",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"os": [
{
"os": "string · операционная система",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"resolution": [
{
"resolution": "string · разрешение экрана",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"device": [
{
"device": "string · тип устройства",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"feedback": [
{
"event_id": "number · ID формы (quiz_feedback.id)",
"open": "number · показов формы",
"finish": "number · отправок"
}
],
"finish": [
{
"event_id": "number · ID финальной страницы (quiz_finish.id)",
"open": "number · показов"
}
],
"result": [
{
"event_id": "number · ID результата (quiz_result.id)",
"open": "number · показов",
"finish": "number · заявок с этим результатом"
}
],
"question": [
{
"event_id": "number · ID вопроса (quiz_question.id)",
"open": "number · показов вопроса",
"asked": "number · ответов",
"asked_custom": "number · ответов в поле «свой ответ»",
"skipped": "number · пропусков"
}
],
"ask": [
{
"event_id": "number · ID вопроса",
"ask": "number · ID варианта ответа",
"asked": "number · сколько раз выбрали"
}
],
"range": [
{
"event_id": "number · ID вопроса-ползунка",
"asked": "number · ответов",
"ask_min": "number · минимальный ответ",
"ask_max": "number · максимальный ответ",
"ask_avg_min": "number · сумма средних по дням (левый бегунок)",
"ask_avg_max": "number · сумма средних по дням (правый бегунок)"
}
],
"rank": [
{
"event_id": "number · ID вопроса-рейтинга",
"mark": "number · оценка",
"asked": "number · сколько раз поставили"
}
],
"input": [
{
"event_id": "number · ID вопроса с полем ввода",
"word": "string · слово из ответов (короче 20 символов)",
"asked": "number · сколько раз встретилось"
}
],
"question_time_spent": [
{
"event_id": "number · ID вопроса",
"cnt": "number · среднее время на вопросе, сек"
}
],
"feedback_time_spent": [
{
"event_id": "number · ID формы",
"cnt": "number · среднее время на форме, сек"
}
],
"time_spent_hour": [
{
"data_hour": "number · час суток (0–23)",
"cnt": "number · среднее время прохождения, сек"
}
],
"hours": [
{
"data_hour": "number · час суток (0–23)",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"week": [
{
"day_of_week": "number · день недели",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"month": [
{
"data_month": "number · месяц (1–12)",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"week_hours": [
{
"day_of_week": "number · день недели",
"data_hour": "number · час",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"daily": [
{
"data": "date · день",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"daily_time_spent": [
{
"data": "date · день",
"cnt": "number · среднее время прохождения, сек"
}
],
"ab": [
{
"ab": "number · ID A/B-варианта (0 — основной)",
"open|start|form|finish": "number · воронка: open (открыли) · start (начали) · form (дошли до формы) · finish (отправили заявку)"
}
],
"ab_time_spent": [
{
"ab": "number · ID A/B-варианта",
"cnt": "number · среднее время прохождения, сек"
}
]
},
"meta": {
"period": [
"date · начало периода",
"date | false · конец периода (false — отчёт за один день)"
]
}
}Очистка аналитики
DELETE /analytics/{id}Безвозвратно удаляет всю собранную статистику квиза за всё время. Сам квиз и заявки не затрагиваются. Право: analytics.write.
Ответ
{
"success": "boolean · true — аналитика удалена"
}



