Перейти к содержимому

Создание формы POST ​

Создайте размещённую форму. Она сразу публикуется по адресу https://frms.click/{tid}, а каждая отправка становится сообщением в вашем аккаунте — см. Формы.

Эндпоинт ​

POST https://api.pocketalert.app/v1/forms

Аутентификация ​

Обязательно

Добавьте в запрос один из этих заголовков:

  • Token: <your-api-key> — получите его в разделе API-ключи
  • Authorization: Bearer <jwt-token> — из входа

Запрос ​

Заголовки ​

ЗаголовокОбязательныйОписание
Token✅Ваш API-ключ
Authorization✅Bearer <jwt-token>

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

ПараметрТипОбязательныйОписание
namestring✅Внутреннее название, до 191 символа. Также используется как заголовок push-уведомления по умолчанию
fieldsarray✅Поля формы, не более 30. Хотя бы одно должно заполняться посетителем
settingsobject❌Заголовок, тексты и оформление. У каждого ключа есть значение по умолчанию
application_tidstring❌Приложение, к которому относятся отправки
device_tidstring❌TID целевого устройства или all. Если не указать, уведомления придут на все устройства
default_levelint❌Уровень приоритета (-2..2) для отправок. См. Уровни приоритета сообщений
push_titlestring❌Шаблон заголовка push-уведомления с токенами {Field label}, до 191 символа
allowed_originsarray❌Хосты, которым разрешено встраивать форму и отправлять её, не более 10. Пустое значение означает, что ограничений нет
max_responsesint❌Закрыть форму после этого количества ответов. 0 (по умолчанию) — без ограничений
closes_atstring❌Время закрытия, RFC 3339. Хранится в UTC
is_activeboolean❌false сразу закрывает форму. По умолчанию true

Поля ​

Каждый элемент fields:

ПараметрТипОбязательныйОписание
idstring✅Уникален в пределах формы: буквы, цифры, _ и -, до 40 символов
typestring✅Один из типов, перечисленных ниже
labelstring✅Отображается над полем ввода, до 200 символов (2000 для paragraph)
placeholderstring❌Только для text, textarea, email, phone, number, url и dropdown
requiredboolean❌Игнорируется полями оформления
optionsarray✅ для полей выбораДо 50 вариантов для dropdown, radio и checkboxes
paramstring✅ для hiddenПараметр URL, из которого читается значение, например utm_source
ГруппаТипыОтправляемое значение
Текстtext, textarea, email, phone, number, url, dateСтрока. text ограничен 1000 символами, textarea — 5000
Выборdropdown, radioОдин из options
ВыборcheckboxesМассив из options
ВыборcheckboxЛогическое значение, отображается как Yes / No
Оценкаrating (1–5), nps (0–10)Число
Оформлениеheading, paragraph, dividerНикогда не отправляются
ОтслеживаниеhiddenБерётся из URL страницы, а не от посетителя

Значения email, телефона, числа, URL и даты проверяются на сервере; проверка в браузере — это удобство, а не защита.

Настройки ​

Все ключи необязательны — то, что вы не укажете, сохраняет значение по умолчанию.

ПараметрТипПо умолчаниюОписание
titlestring""Заголовок над формой, до 200 символов
top_textstring""Вводный текст, до 2000 символов. Простой текст; ссылки становятся кликабельными
bottom_textstring""Текст под кнопкой, до 2000 символов
success_messagestringThanks! Your response has been sent.Показывается после отправки, до 500 символов
closed_messagestringThis form is no longer accepting responses.Показывается, когда форма закрыта
background_colorstring#f5f5f4Фон страницы, #rrggbb
card_colorstring#ffffffФон формы
text_colorstring#1c1917Цвет текста
primary_colorstring#3f5cadАкцентный цвет и, если не переопределён, цвет кнопки
font_familystringInterШрифт Google Fonts по названию
font_sizeint1612–24
font_weightint400300, 400, 500, 600 или 700
border_radiusint100–48
hide_brandingbooleanfalseСкрывает ссылку «Powered by Pocket Alert». Только для платных тарифов — на бесплатном тарифе API сбрасывает значение в false
submitobject—{ "text": "Submit", "color": "", "size": "md" }. size — sm, md или lg; пустой color следует за primary_color

Шаблон заголовка push-уведомления ​

push_title формирует заголовок уведомления из ответов:

New lead: {Name} ({Email})

Токены ссылаются на поля по названию без учёта регистра, а также {form} — для названия формы. Токены без ответа пропускаются; если ничего не осталось, заголовок становится Form: {name}. Шаблон никогда не показывается на публичной странице.

Разрешённые источники ​

Идентификатор формы передаётся в её публичной ссылке, поэтому по умолчанию встроить форму может любой, у кого она есть. allowed_origins это ограничивает: встраивать форму могут только перечисленные хосты, а отправка, у которой Origin (или Referer) не входит в список, отклоняется с ответом 403.

Указывайте хосты, а не URL: example.com, app.example.com, *.example.com для всех поддоменов, localhost:3000 при разработке. Префикс www. игнорируется.

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

bash
curl -X POST "https://api.pocketalert.app/v1/forms" \
  -H "Token: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact form",
    "push_title": "New lead: {Name}",
    "fields": [
      { "id": "name", "type": "text", "label": "Name", "required": true },
      { "id": "email", "type": "email", "label": "Email", "required": true },
      { "id": "message", "type": "textarea", "label": "Message" },
      { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
    ],
    "settings": {
      "title": "Get in touch",
      "top_text": "We reply within one business day.",
      "primary_color": "#3f5cad"
    }
  }'
javascript
const response = await fetch('https://api.pocketalert.app/v1/forms', {
  method: 'POST',
  headers: {
    'Token': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Contact form',
    push_title: 'New lead: {Name}',
    fields: [
      { id: 'name', type: 'text', label: 'Name', required: true },
      { id: 'email', type: 'email', label: 'Email', required: true },
      { id: 'message', type: 'textarea', label: 'Message' }
    ],
    settings: { title: 'Get in touch' }
  })
});

const form = await response.json();
console.log('Form link:', `https://frms.click/${form.tid}`);
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms',
    headers={'Token': 'your-api-key'},
    json={
        'name': 'Contact form',
        'push_title': 'New lead: {Name}',
        'fields': [
            {'id': 'name', 'type': 'text', 'label': 'Name', 'required': True},
            {'id': 'email', 'type': 'email', 'label': 'Email', 'required': True},
            {'id': 'message', 'type': 'textarea', 'label': 'Message'},
        ],
        'settings': {'title': 'Get in touch'},
    }
)

form = response.json()
print(f"Form link: https://frms.click/{form['tid']}")
php
$form = Http::withHeaders([
    'Token' => 'your-api-key',
])->post('https://api.pocketalert.app/v1/forms', [
    'name' => 'Contact form',
    'push_title' => 'New lead: {Name}',
    'fields' => [
        ['id' => 'name', 'type' => 'text', 'label' => 'Name', 'required' => true],
        ['id' => 'email', 'type' => 'email', 'label' => 'Email', 'required' => true],
        ['id' => 'message', 'type' => 'textarea', 'label' => 'Message'],
    ],
    'settings' => ['title' => 'Get in touch'],
])->json();

echo 'Form link: https://frms.click/'.$form['tid'];

Ответ ​

Успешный ответ ​

201 Created

Форма опубликована. Поделитесь ссылкой https://frms.click/{tid} или встройте форму — см. Формы.

Тело ответа имеет ту же структуру, что и один элемент из Получения всех форм.

json
{
  "tid": "vml19aihrga216gt8apc5e3m9",
  "name": "Contact form",
  "fields": [
    { "id": "name", "type": "text", "label": "Name", "required": true },
    { "id": "email", "type": "email", "label": "Email", "required": true },
    { "id": "message", "type": "textarea", "label": "Message" },
    { "id": "src", "type": "hidden", "label": "Source", "param": "utm_source" }
  ],
  "settings": {
    "title": "Get in touch",
    "top_text": "We reply within one business day.",
    "success_message": "Thanks! Your response has been sent.",
    "closed_message": "This form is no longer accepting responses.",
    "background_color": "#f5f5f4",
    "card_color": "#ffffff",
    "text_color": "#1c1917",
    "primary_color": "#3f5cad",
    "font_family": "Inter",
    "font_size": 16,
    "font_weight": 400,
    "border_radius": 10,
    "hide_branding": false,
    "submit": { "text": "Submit", "color": "", "size": "md" }
  },
  "application_tid": "",
  "device_tid": "",
  "default_level": null,
  "push_title": "New lead: {Name}",
  "allowed_origins": [],
  "max_responses": 0,
  "closes_at": null,
  "closed": false,
  "is_active": true,
  "submissions_count": 0,
  "last_submission_at": "",
  "created_at": "23.09.2026 11:40:02"
}

Ответы с ошибками ​

СтатусОписание
400Ошибка валидации — поле error указывает, какое поле или настройка неверны
401Не авторизовано — токен неверный или отсутствует
403Вы достигли лимита форм, доступного на вашем тарифе
500Не удалось создать форму

Документация Pocket Alert