Ir para o conteúdo

Criar formulário POST ​

Crie um formulário hospedado. Ele é publicado na hora em https://frms.click/{tid}, e cada envio vira uma mensagem na sua conta — veja Formulários.

Endpoint ​

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

Autenticação ​

Obrigatório

Inclua um destes cabeçalhos na sua requisição:

  • Token: <your-api-key> — Obtenha em Chaves de API
  • Authorization: Bearer <jwt-token> — Obtido em Entrar

Requisição ​

Cabeçalhos ​

CabeçalhoObrigatórioDescrição
Token✅Sua chave de API
Authorization✅Bearer <jwt-token>

Parâmetros do corpo ​

ParâmetroTipoObrigatórioDescrição
namestring✅Nome interno, até 191 caracteres. Também é o título padrão da notificação push
fieldsarray✅Os campos do formulário, máximo de 30. Pelo menos um deve ser algo que o visitante preenche
settingsobject❌Título, textos e design. Cada chave tem um valor padrão
application_tidstring❌Aplicativo ao qual os envios pertencem
device_tidstring❌TID do dispositivo de destino, ou all. Omita para todos os dispositivos
default_levelint❌Nível de prioridade (-2..2) para os envios. Veja Níveis de prioridade da mensagem
push_titlestring❌Modelo do título push com tokens {Field label}, até 191 caracteres
allowed_originsarray❌Hosts autorizados a incorporar e enviar o formulário, máximo de 10. Vazio significa qualquer lugar
max_responsesint❌Fecha o formulário após este número de respostas. 0 (padrão) é ilimitado
closes_atstring❌Horário de encerramento, RFC 3339. Armazenado em UTC
is_activeboolean❌false fecha o formulário imediatamente. O padrão é true

Campos ​

Cada item em fields:

ParâmetroTipoObrigatórioDescrição
idstring✅Único dentro do formulário: letras, dígitos, _ e -, até 40 caracteres
typestring✅Um dos tipos abaixo
labelstring✅Exibido acima do campo, até 200 caracteres (2000 para paragraph)
placeholderstring❌Apenas para text, textarea, email, phone, number, url e dropdown
requiredboolean❌Ignorado em campos de layout
optionsarray✅ em campos de escolhaAté 50 itens para dropdown, radio e checkboxes
paramstring✅ para hiddenParâmetro da URL de onde o valor é lido, ex.: utm_source
GrupoTiposValor enviado
Textotext, textarea, email, phone, number, url, dateString. text é limitado a 1000 caracteres, textarea a 5000
Escolhadropdown, radioUm dos options
EscolhacheckboxesArray de options
EscolhacheckboxBooleano, exibido como Yes / No
Avaliaçãorating (1–5), nps (0–10)Número
Layoutheading, paragraph, dividerNunca enviado
RastreamentohiddenObtido da URL da página, não do visitante

Valores de e-mail, telefone, número, URL e data são validados no servidor; a verificação no navegador é só uma conveniência, não a proteção.

Configurações ​

Todas as chaves são opcionais — o que você não informar mantém o padrão.

ParâmetroTipoPadrãoDescrição
titlestring""Título acima do formulário, até 200 caracteres
top_textstring""Texto de introdução, até 2000 caracteres. Texto simples; links ficam clicáveis
bottom_textstring""Texto abaixo do botão, até 2000 caracteres
success_messagestringThanks! Your response has been sent.Exibida após um envio, até 500 caracteres
closed_messagestringThis form is no longer accepting responses.Exibida quando o formulário está fechado
background_colorstring#f5f5f4Fundo da página, #rrggbb
card_colorstring#ffffffFundo do formulário
text_colorstring#1c1917Texto
primary_colorstring#3f5cadDestaque e, salvo se substituído, o botão
font_familystringInterUma fonte do Google Fonts pelo nome
font_sizeint1612–24
font_weightint400300, 400, 500, 600 ou 700
border_radiusint100–48
hide_brandingbooleanfalseOculta o link "Powered by Pocket Alert". Apenas em planos pagos — no plano gratuito a API o redefine para false
submitobject—{ "text": "Submit", "color": "", "size": "md" }. size é sm, md ou lg; um color vazio segue primary_color

Modelo do título push ​

push_title monta o título da notificação a partir das respostas:

New lead: {Name} ({Email})

Os tokens referenciam campos pelo rótulo, sem diferenciar maiúsculas, além de {form} para o nome do formulário. Tokens sem resposta são removidos; se nada sobrar, o título volta para Form: {name}. O modelo nunca é exibido na página pública.

Origens permitidas ​

O ID do formulário circula no link público, então por padrão qualquer pessoa que o tenha pode incorporar o formulário. allowed_origins impede isso: apenas os hosts listados podem exibir o formulário, e um envio cujo Origin (ou Referer) não esteja na lista é rejeitado com 403.

Informe hosts, não URLs: example.com, app.example.com, *.example.com para todos os subdomínios, localhost:3000 durante o desenvolvimento. O prefixo www. é ignorado.

Exemplo de requisição ​

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'];

Resposta ​

Resposta de sucesso ​

201 Created

O formulário está no ar. Compartilhe https://frms.click/{tid}, ou incorpore-o — veja Formulários.

O corpo tem o mesmo formato de um item de Listar todos os formulários.

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"
}

Respostas de erro ​

StatusDescrição
400Erro de validação — o campo error indica qual campo ou configuração está incorreto
401Não autorizado — token inválido ou ausente
403Você atingiu o número de formulários permitido pelo seu plano
500Falha ao criar o formulário

Documentação do Pocket Alert