Saltar al contenido

Crear formulario POST ​

Crea un formulario alojado. Se publica al instante en https://frms.click/{tid}, y cada envío se convierte en un mensaje en tu cuenta. Consulta Formularios.

Endpoint ​

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

Autenticación ​

Obligatorio

Incluye una de estas cabeceras en tu solicitud:

Solicitud ​

Cabeceras ​

CabeceraObligatoriaDescripción
Token✅Tu clave de API
Authorization✅Bearer <jwt-token>

Parámetros del cuerpo ​

ParámetroTipoObligatorioDescripción
namestring✅Nombre interno, de hasta 191 caracteres. También es el título push predeterminado
fieldsarray✅Los campos del formulario, máximo 30. Al menos uno debe ser un campo que el visitante rellene
settingsobject❌Título, textos y diseño. Cada clave tiene un valor predeterminado
application_tidstring❌Aplicación a la que pertenecen los envíos
device_tidstring❌TID del dispositivo de destino, o all. Omítelo para todos los dispositivos
default_levelint❌Nivel de prioridad (-2..2) para los envíos. Consulta Niveles de prioridad de mensajes
push_titlestring❌Plantilla del título push con tokens {Field label}, de hasta 191 caracteres
allowed_originsarray❌Hosts autorizados a insertar y enviar el formulario, máximo 10. Vacío significa cualquiera
max_responsesint❌Cierra el formulario tras este número de respuestas. 0 (predeterminado) es ilimitado
closes_atstring❌Hora de cierre, RFC 3339. Se guarda en UTC
is_activeboolean❌false cierra el formulario de inmediato. Por defecto es true

Campos ​

Cada entrada de fields:

ParámetroTipoObligatorioDescripción
idstring✅Único dentro del formulario: letras, dígitos, _ y -, de hasta 40 caracteres
typestring✅Uno de los tipos siguientes
labelstring✅Se muestra encima del campo, de hasta 200 caracteres (2000 para paragraph)
placeholderstring❌Solo para text, textarea, email, phone, number, url y dropdown
requiredboolean❌Lo ignoran los campos de maquetación
optionsarray✅ en campos de elecciónHasta 50 entradas para dropdown, radio y checkboxes
paramstring✅ para hiddenParámetro de URL del que se lee el valor, p. ej. utm_source
GrupoTiposValor enviado
Textotext, textarea, email, phone, number, url, dateCadena. text admite como máximo 1000 caracteres, textarea 5000
Eleccióndropdown, radioUno de options
EleccióncheckboxesArray de options
EleccióncheckboxBooleano, mostrado como Yes / No
Valoraciónrating (1–5), nps (0–10)Número
Maquetaciónheading, paragraph, dividerNunca se envían
SeguimientohiddenSe toma de la URL de la página, no del visitante

Los valores de email, teléfono, número, URL y fecha se validan en el servidor; la comprobación del navegador es una comodidad, no la protección.

Configuración ​

Todas las claves son opcionales: lo que omitas conserva su valor predeterminado.

ParámetroTipoPredeterminadoDescripción
titlestring""Encabezado sobre el formulario, de hasta 200 caracteres
top_textstring""Texto introductorio, de hasta 2000 caracteres. Texto plano; los enlaces se vuelven clicables
bottom_textstring""Texto bajo el botón, de hasta 2000 caracteres
success_messagestringThanks! Your response has been sent.Se muestra tras un envío, de hasta 500 caracteres
closed_messagestringThis form is no longer accepting responses.Se muestra cuando el formulario está cerrado
background_colorstring#f5f5f4Fondo de la página, #rrggbb
card_colorstring#ffffffFondo del formulario
text_colorstring#1c1917Texto
primary_colorstring#3f5cadColor de acento y, salvo que se sobrescriba, del botón
font_familystringInterUna fuente de Google por nombre
font_sizeint1612–24
font_weightint400300, 400, 500, 600 o 700
border_radiusint100–48
hide_brandingbooleanfalseOculta el enlace «Powered by Pocket Alert». Solo en planes de pago; en el plan gratuito la API lo restablece a false
submitobject—{ "text": "Submit", "color": "", "size": "md" }. size es sm, md o lg; un color vacío sigue a primary_color

Plantilla del título push ​

push_title construye el título de la notificación a partir de las respuestas:

New lead: {Name} ({Email})

Los tokens hacen referencia a los campos por etiqueta, sin distinguir mayúsculas, más {form} para el nombre del formulario. Los tokens sin respuesta se eliminan; si no queda nada, el título vuelve a Form: {name}. La plantilla nunca se muestra en la página pública.

Orígenes permitidos ​

El id del formulario viaja en su enlace público, así que por defecto cualquiera que lo tenga puede insertarlo. allowed_origins lo evita: solo los hosts indicados pueden mostrar el formulario, y un envío cuyo Origin (o Referer) no esté en la lista se rechaza con 403.

Escribe hosts, no URL: example.com, app.example.com, *.example.com para todos los subdominios, localhost:3000 durante el desarrollo. www. se ignora.

Ejemplo de solicitud ​

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

Respuesta ​

Respuesta de éxito ​

201 Created

El formulario está activo. Comparte https://frms.click/{tid} o insértalo. Consulta Formularios.

El cuerpo tiene la misma forma que una entrada de Obtener todos los formularios.

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

Respuestas de error ​

EstadoDescripción
400Error de validación: el campo error indica qué campo o configuración es incorrecto
401No autorizado: token no válido o ausente
403Has alcanzado el número de formularios que permite tu plan
500No se pudo crear el formulario

Documentación de Pocket Alert