REST API Matomba

Время чтения: 23 мин. 0 сек.16.11.2026

Начало работы

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 — аналитика удалена"
}
Лого https://matomba.ru

Выберите один из 45 сценариев для вашего бизнеса, настройте дизайн и начните собирать заявки

Создать квиз бесплатно

Часто задаваемые вопросы

+Где взять API-ключ?

Ключ создаётся в личном кабинете в разделе «API». Нажмите «Создать ключ», укажите название и выберите нужные права (scopes). Секретная часть ключа показывается только один раз при создании — обязательно сохраните её.

+Какие права (scopes) бывают у ключей?

quizzes.read — просмотр квизов; quizzes.write — создание, изменение и копирование квизов; leads.read — получение заявок (сделок). Ключ получает только те права, которые вы выбрали при создании.

+Как передать ключ в запросе?

Ключ передаётся в заголовке Authorization с префиксом Bearer. Пример: Authorization: Bearer matomba__.

+Какой формат ошибок возвращает API?

При любой ошибке сервер возвращает HTTP-код и JSON-объект с единственным полем error, в котором лежит текст ошибки. Например: {"error": "Недостаточно прав"}.

+Как получить список всех квизов?

Выполните GET-запрос на /api/quiz. В ответе придёт массив data.apps со всеми активными квизами и meta.count с их количеством. Пагинации нет — возвращаются все квизы сразу.

+Как создать копию квиза?

Используйте POST-запрос на /api/quiz/{id}, где {id} — идентификатор существующего квиза. Тело запроса не требуется. Лимит тарифа проверяется так же, как при создании.

+Что происходит при удалении квиза?

Выполняется мягкое удаление: квиз помечается неактивным и перестаёт отдаваться через API, домен снимается. Данные остаются в системе. Восстановление возможно только через техническую поддержку.

+Как получить заявки (сделки) по квизам?

Выполните GET-запрос на /api/deal. Можно отфильтровать по ID квизов (app=1,2,3) и по периоду (date_start и date_end в формате YYYY-MM-DD). Размер страницы — 100 заявок, номер страницы передаётся в параметре page.

+Почему при запросе аналитики возвращается ошибка 403?

Ошибка 403 в аналитике может означать две вещи: либо у ключа нет права analytics.read, либо выбранный период недоступен на вашем тарифе (например, вы запросили 90 дней на тарифе MEDIUM). Для тарифных ограничений возвращается код analytics403.

+Как передать A/B-версию квиза при создании?

Массив A/B-версий передаётся в ключе quiz_ab верхнего уровня тела запроса (не внутри app). Каждая версия содержит собственную структуру: landing, showcase и questions.

Еще остались вопросы?

Напишите нам в чат или социальные сети!

Пользуясь нашим сайтом, вы соглашаетесь с тем, что мы используем cookies 🍪

Окей