Ir para o conteúdo

Enviar formulário POST ​

Envie uma resposta. A submissão vira uma mensagem na conta do dono e é enviada como notificação push para o celular dele — o mesmo fluxo que uma chamada de webhook percorre. Sem autenticação.

Endpoint ​

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

Autenticação ​

Não é necessária

Qualquer pessoa que tenha o link pode enviar. O dono controla quem pode: veja origens permitidas e os limites abaixo.

Requisição ​

Parâmetros de caminho ​

ParâmetroTipoObrigatórioDescrição
tidstring✅Identificador do formulário

Parâmetros do corpo ​

ParâmetroTipoObrigatórioDescrição
valuesobject✅Respostas indexadas pelo id do campo
websitestring❌Honeypot. Deixe de fora; qualquer valor não vazio é tratado como bot

Valor por tipo de campo:

TipoValor
text, textarea, email, phone, number, urlString. O formato é validado para email, phone, number e URL
dateString, YYYY-MM-DD
dropdown, radioString, uma das options do campo
checkboxesArray de strings de options
checkboxBoolean
ratingNúmero, 1–5
npsNúmero, 0–10
hiddenString, normalmente obtida da URL da página

Campos de layout (heading, paragraph, divider) não recebem valor, e chaves desconhecidas são ignoradas. O corpo tem limite de 64 KB.

Exemplo de requisição ​

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())

Resposta ​

Resposta de sucesso ​

200 OK

json
{ "status": "ok" }

O dono recebe uma notificação push montada com as respostas. Nada sobre o dono — o plano dele, seus dispositivos, sua cota — é exposto ao visitante.

Erros de validação ​

400 Bad Request

fields mapeia o id de um campo para o motivo da rejeição, que é o que a página do formulário exibe abaixo de cada campo.

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

Formulário fechado ​

410 Gone

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

error traz o closed_message próprio do dono.

Limites ​

LimiteValor
Por IP10 envios por minuto
Por formulário60 por minuto, 300 por hora
Cota do donoCada envio usa uma mensagem da cota diária dele

Um envio que ultrapassaria o limite diário de mensagens do dono recebe um 429 neutro, com o cabeçalho Retry-After e sem menção ao plano.

Respostas de erro ​

StatusDescrição
400Corpo inválido, ou fields lista as respostas que precisam ser corrigidas
403O formulário não aceita envios deste site — veja origens permitidas
404Formulário não encontrado
410O formulário está fechado
429Muitos envios, ou o dono esgotou as mensagens de hoje
500O formulário está mal configurado, ou a mensagem não pôde ser criada

Documentação do Pocket Alert