Создание формы POST
Создайте размещённую форму. Она сразу публикуется по адресу https://frms.click/{tid}, а каждая отправка становится сообщением в вашем аккаунте — см. Формы.
Эндпоинт
POST https://api.pocketalert.app/v1/formsАутентификация
Обязательно
Добавьте в запрос один из этих заголовков:
Запрос
Заголовки
| Заголовок | Обязательный | Описание |
|---|---|---|
Token | ✅ | Ваш API-ключ |
Authorization | ✅ | Bearer <jwt-token> |
Параметры тела запроса
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
name | string | ✅ | Внутреннее название, до 191 символа. Также используется как заголовок push-уведомления по умолчанию |
fields | array | ✅ | Поля формы, не более 30. Хотя бы одно должно заполняться посетителем |
settings | object | ❌ | Заголовок, тексты и оформление. У каждого ключа есть значение по умолчанию |
application_tid | string | ❌ | Приложение, к которому относятся отправки |
device_tid | string | ❌ | TID целевого устройства или all. Если не указать, уведомления придут на все устройства |
default_level | int | ❌ | Уровень приоритета (-2..2) для отправок. См. Уровни приоритета сообщений |
push_title | string | ❌ | Шаблон заголовка push-уведомления с токенами {Field label}, до 191 символа |
allowed_origins | array | ❌ | Хосты, которым разрешено встраивать форму и отправлять её, не более 10. Пустое значение означает, что ограничений нет |
max_responses | int | ❌ | Закрыть форму после этого количества ответов. 0 (по умолчанию) — без ограничений |
closes_at | string | ❌ | Время закрытия, RFC 3339. Хранится в UTC |
is_active | boolean | ❌ | false сразу закрывает форму. По умолчанию true |
Поля
Каждый элемент fields:
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
id | string | ✅ | Уникален в пределах формы: буквы, цифры, _ и -, до 40 символов |
type | string | ✅ | Один из типов, перечисленных ниже |
label | string | ✅ | Отображается над полем ввода, до 200 символов (2000 для paragraph) |
placeholder | string | ❌ | Только для text, textarea, email, phone, number, url и dropdown |
required | boolean | ❌ | Игнорируется полями оформления |
options | array | ✅ для полей выбора | До 50 вариантов для dropdown, radio и checkboxes |
param | string | ✅ для 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 и даты проверяются на сервере; проверка в браузере — это удобство, а не защита.
Настройки
Все ключи необязательны — то, что вы не укажете, сохраняет значение по умолчанию.
| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
title | string | "" | Заголовок над формой, до 200 символов |
top_text | string | "" | Вводный текст, до 2000 символов. Простой текст; ссылки становятся кликабельными |
bottom_text | string | "" | Текст под кнопкой, до 2000 символов |
success_message | string | Thanks! Your response has been sent. | Показывается после отправки, до 500 символов |
closed_message | string | This form is no longer accepting responses. | Показывается, когда форма закрыта |
background_color | string | #f5f5f4 | Фон страницы, #rrggbb |
card_color | string | #ffffff | Фон формы |
text_color | string | #1c1917 | Цвет текста |
primary_color | string | #3f5cad | Акцентный цвет и, если не переопределён, цвет кнопки |
font_family | string | Inter | Шрифт Google Fonts по названию |
font_size | int | 16 | 12–24 |
font_weight | int | 400 | 300, 400, 500, 600 или 700 |
border_radius | int | 10 | 0–48 |
hide_branding | boolean | false | Скрывает ссылку «Powered by Pocket Alert». Только для платных тарифов — на бесплатном тарифе API сбрасывает значение в false |
submit | object | — | { "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. игнорируется.
Пример запроса
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"
}
}'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}`);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']}")$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} или встройте форму — см. Формы.
Тело ответа имеет ту же структуру, что и один элемент из Получения всех форм.
{
"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 | Не удалось создать форму |