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/formsAutenticación
Obligatorio
Incluye una de estas cabeceras en tu solicitud:
Token: <your-api-key>— Obtenla en Claves de APIAuthorization: Bearer <jwt-token>— Desde Iniciar sesión
Solicitud
Cabeceras
| Cabecera | Obligatoria | Descripción |
|---|---|---|
Token | ✅ | Tu clave de API |
Authorization | ✅ | Bearer <jwt-token> |
Parámetros del cuerpo
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
name | string | ✅ | Nombre interno, de hasta 191 caracteres. También es el título push predeterminado |
fields | array | ✅ | Los campos del formulario, máximo 30. Al menos uno debe ser un campo que el visitante rellene |
settings | object | ❌ | Título, textos y diseño. Cada clave tiene un valor predeterminado |
application_tid | string | ❌ | Aplicación a la que pertenecen los envíos |
device_tid | string | ❌ | TID del dispositivo de destino, o all. Omítelo para todos los dispositivos |
default_level | int | ❌ | Nivel de prioridad (-2..2) para los envíos. Consulta Niveles de prioridad de mensajes |
push_title | string | ❌ | Plantilla del título push con tokens {Field label}, de hasta 191 caracteres |
allowed_origins | array | ❌ | Hosts autorizados a insertar y enviar el formulario, máximo 10. Vacío significa cualquiera |
max_responses | int | ❌ | Cierra el formulario tras este número de respuestas. 0 (predeterminado) es ilimitado |
closes_at | string | ❌ | Hora de cierre, RFC 3339. Se guarda en UTC |
is_active | boolean | ❌ | false cierra el formulario de inmediato. Por defecto es true |
Campos
Cada entrada de fields:
| Parámetro | Tipo | Obligatorio | Descripción |
|---|---|---|---|
id | string | ✅ | Único dentro del formulario: letras, dígitos, _ y -, de hasta 40 caracteres |
type | string | ✅ | Uno de los tipos siguientes |
label | string | ✅ | Se muestra encima del campo, de hasta 200 caracteres (2000 para paragraph) |
placeholder | string | ❌ | Solo para text, textarea, email, phone, number, url y dropdown |
required | boolean | ❌ | Lo ignoran los campos de maquetación |
options | array | ✅ en campos de elección | Hasta 50 entradas para dropdown, radio y checkboxes |
param | string | ✅ para hidden | Parámetro de URL del que se lee el valor, p. ej. utm_source |
| Grupo | Tipos | Valor enviado |
|---|---|---|
| Texto | text, textarea, email, phone, number, url, date | Cadena. text admite como máximo 1000 caracteres, textarea 5000 |
| Elección | dropdown, radio | Uno de options |
| Elección | checkboxes | Array de options |
| Elección | checkbox | Booleano, mostrado como Yes / No |
| Valoración | rating (1–5), nps (0–10) | Número |
| Maquetación | heading, paragraph, divider | Nunca se envían |
| Seguimiento | hidden | Se 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ámetro | Tipo | Predeterminado | Descripción |
|---|---|---|---|
title | string | "" | Encabezado sobre el formulario, de hasta 200 caracteres |
top_text | string | "" | Texto introductorio, de hasta 2000 caracteres. Texto plano; los enlaces se vuelven clicables |
bottom_text | string | "" | Texto bajo el botón, de hasta 2000 caracteres |
success_message | string | Thanks! Your response has been sent. | Se muestra tras un envío, de hasta 500 caracteres |
closed_message | string | This form is no longer accepting responses. | Se muestra cuando el formulario está cerrado |
background_color | string | #f5f5f4 | Fondo de la página, #rrggbb |
card_color | string | #ffffff | Fondo del formulario |
text_color | string | #1c1917 | Texto |
primary_color | string | #3f5cad | Color de acento y, salvo que se sobrescriba, del botón |
font_family | string | Inter | Una fuente de Google por nombre |
font_size | int | 16 | 12–24 |
font_weight | int | 400 | 300, 400, 500, 600 o 700 |
border_radius | int | 10 | 0–48 |
hide_branding | boolean | false | Oculta el enlace «Powered by Pocket Alert». Solo en planes de pago; en el plan gratuito la API lo restablece a false |
submit | object | — | { "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
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"
}
}'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}`);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']}")$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.
{
"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
| Estado | Descripción |
|---|---|
400 | Error de validación: el campo error indica qué campo o configuración es incorrecto |
401 | No autorizado: token no válido o ausente |
403 | Has alcanzado el número de formularios que permite tu plan |
500 | No se pudo crear el formulario |