跳到正文

提交表单 POST ​

发送响应。提交的内容会在所有者的账户中生成一条消息,并推送到其手机,走的是与 Webhook 调用相同的流程。无需身份验证。

端点 ​

POST https://api.pocketalert.app/v1/forms/{tid}/submit

身份验证 ​

无需身份验证

任何持有链接的人都可以提交。所有者可以控制谁能提交:参见允许的来源以及下方的限制。

请求 ​

路径参数 ​

参数类型必填说明
tidstring✅表单标识符

请求体参数 ​

参数类型必填说明
valuesobject✅以字段 id 为键的回答
websitestring❌蜜罐字段。请不要填写;任何非空值都会被视为机器人提交

各字段类型对应的值:

类型值
text、textarea、email、phone、number、url字符串。其中 email、phone、number 和 url 会校验格式
date字符串,格式为 YYYY-MM-DD
dropdown、radio字符串,必须是字段 options 中的一项
checkboxes字符串数组,元素取自 options
checkbox布尔值
rating数字,1–5
nps数字,0–10
hidden字符串,通常取自页面 URL

布局字段(heading、paragraph、divider)不接受值,未知的键会被忽略。请求体上限为 64 KB。

请求示例 ​

bash
curl -X POST "https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit" \
  -H "Content-Type: application/json" \
  -d '{
    "values": {
      "name": "Jane Doe",
      "email": "[email protected]",
      "message": "Do you ship to Canada?",
      "src": "newsletter"
    }
  }'
javascript
const response = await fetch(
  'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      values: {
        name: 'Jane Doe',
        email: '[email protected]',
        message: 'Do you ship to Canada?'
      }
    })
  }
);

const result = await response.json();
if (response.status === 400) {
  // result.fields = { email: "Enter a valid email address" }
  console.log(result.fields);
}
python
import requests

response = requests.post(
    'https://api.pocketalert.app/v1/forms/vml19aihrga216gt8apc5e3m9/submit',
    json={
        'values': {
            'name': 'Jane Doe',
            'email': '[email protected]',
            'message': 'Do you ship to Canada?',
        }
    }
)

print(response.status_code, response.json())

响应 ​

成功响应 ​

200 OK

json
{ "status": "ok" }

所有者会收到一条由回答内容生成的推送。访客无法看到所有者的任何信息,包括其套餐、设备和配额。

校验错误 ​

400 Bad Request

fields 将字段 id 映射到被拒绝的原因,表单页面会将其显示在对应输入框下方。

json
{
  "error": "Please check the highlighted fields.",
  "fields": {
    "email": "Enter a valid email address",
    "name": "This field is required"
  }
}

表单已关闭 ​

410 Gone

json
{
  "error": "This form is no longer accepting responses.",
  "closed": true
}

error 字段返回所有者自定义的 closed_message。

限制 ​

限制值
每个 IP每分钟 10 次提交
每个表单每分钟 60 次,每小时 300 次
所有者配额每次提交占用所有者每日额度中的一条消息

如果某次提交会超出所有者的每日消息上限,将返回中性的 429 响应,附带 Retry-After 响应头,且不会提及套餐信息。

错误响应 ​

状态码说明
400请求体无效,或 fields 列出了需要修正的回答
403该表单不接受来自此站点的提交,参见允许的来源
404未找到表单
410表单已关闭
429提交过于频繁,或所有者今日消息已用完
500表单配置有误,或无法创建消息

Pocket Alert 文档