跳到正文

创建表单 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 个字符。同时也是默认的推送标题
fieldsarray✅表单字段,最多 30 个。至少需要一个由访问者填写的字段
settingsobject❌标题、文本和外观设计。每个键都有默认值
application_tidstring❌提交内容所属的应用
device_tidstring❌目标设备 TID,或 all。省略则发送到所有设备
default_levelint❌提交内容的优先级(-2..2)。参见 消息优先级
push_titlestring❌推送标题模板,使用 {Field label} 占位符,最多 191 个字符
allowed_originsarray❌允许嵌入和提交表单的域名,最多 10 个。留空表示不限制
max_responsesint❌达到此提交数量后关闭表单。0(默认)表示不限
closes_atstring❌关闭时间,RFC 3339 格式。以 UTC 存储
is_activeboolean❌设为 false 则立即关闭表单。默认为 true

字段 ​

fields 中的每一项:

参数类型必填说明
idstring✅在表单内唯一:字母、数字、_ 和 -,最多 40 个字符
typestring✅以下类型之一
labelstring✅显示在输入框上方,最多 200 个字符(paragraph 为 2000 个)
placeholderstring❌仅适用于 text、textarea、email、phone、number、url 和 dropdown
requiredboolean❌布局字段会忽略此项
optionsarray✅ 用于选择类字段dropdown、radio 和 checkboxes 最多 50 个选项
paramstring✅ 用于 hidden读取值的 URL 参数,例如 utm_source
分组类型提交的值
文本text、textarea、email、phone、number、url、date字符串。text 上限 1000 个字符,textarea 上限 5000 个字符
选择dropdown、radiooptions 中的一个
选择checkboxesoptions 组成的数组
选择checkbox布尔值,显示为 Yes / No
评分rating(1–5)、nps(0–10)数字
布局heading、paragraph、divider从不提交
追踪hidden取自页面 URL,而非访问者输入

邮箱、手机号、数字、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 字体
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_title 会根据回答生成通知标题:

New lead: {Name} ({Email})

占位符通过字段标签引用字段,不区分大小写,另外 {form} 表示表单名称。没有回答的占位符会被移除;如果没有剩余内容,标题将回退为 Form: {name}。该模板永远不会在公开页面中显示。

允许的来源 ​

表单 ID 包含在公开链接中,因此默认情况下任何持有该链接的人都可以嵌入表单。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 文档