Forms API

Introducción

Con la Forms API (v4), tu propio código crea encuestas y formularios, los publica, recoge las respuestas y lee los resultados. Es la misma API que usa el editor de StrawPoll.

• URL base: https://api.strawpoll.com/v4 (también disponible en https://strawpoll.com/api/v4)
• Formato: JSON tanto de entrada como de salida. Las marcas de tiempo son cadenas ISO 8601, y los identificadores, UUID.
• Especificación legible por máquina: OpenAPI 3.1

Cada formulario tiene un identificador público corto, el slug, como en https://strawpoll.com/r/AZPg4n1Td3-hnVAj6Q8p. Todos los endpoints de formularios esperan el slug.

Autenticación

Crea una clave en Ajustes → Claves de API. Solo se muestra una vez: guárdala en un lugar seguro. Envíala con cada petición:

curl https://api.strawpoll.com/v4/me 
  -H "X-API-Key: sp_your_key"

Authorization: Bearer sp_your_key también funciona. Una clave actúa en tu nombre: puede gestionar todos los formularios que gestionas en el panel, incluidos los de los espacios de trabajo de los que eres miembro. Elimina una clave en los ajustes para revocarla al instante.

Los endpoints para los participantes, submit y verify, no piden clave desde un navegador. Las peticiones de scripts, bibliotecas HTTP, navegadores headless, bots y agentes de IA, reconocidos por su user agent, se rechazan con automated si no envían una clave.

Errores

Los errores devuelven el estado HTTP correspondiente y un cuerpo JSON:

{ "error": "This poll is closed.", "code": "closed" }

error está pensado para personas; code, cuando aparece, para tu código.

Límites de frecuencia

120 peticiones por minuto y por clave. Sin clave, las peticiones de un navegador se cuentan por cuenta con sesión iniciada o por navegador (mediante su cookie de voto), hasta 3000 por minuto para todos los navegadores detrás de una misma dirección IP; las peticiones sin ninguna de las dos se cuentan por dirección IP. Cada respuesta indica tu cuota en X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos Unix).

Estructura de un formulario

Un formulario es una lista de sections. Las secciones de pregunta contienen fields, y los campos de opciones contienen choices.

Los ajustes válidos para todo el formulario están en properties. Los más usados:

La especificación OpenAPI enumera todas las propiedades de las secciones, fields y choices.

Crear una encuesta

curl https://api.strawpoll.com/v4/forms 
  -H "X-API-Key: sp_your_key" 
  -H "Content-Type: application/json" 
  -d '{
    "title": "¿Dónde comemos?",
    "status": "published",
    "properties": { "responseDuplicateCheck": "ip", "resultsVisibility": "public" },
    "sections": [{
      "type": "multiple_choice",
      "fields": [{
        "type": "multiple_choice",
        "label": "¿Dónde comemos?",
        "properties": { "isMultipleChoice": false },
        "choices": [{ "label": "Pizza" }, { "label": "Sushi" }, { "label": "Tacos" }]
      }]
    }]
  }'

La respuesta contiene el formulario completo, con los identificadores generados y sus enlaces en urls.formUrl y urls.resultsUrl. Sin "status": "published", un formulario empieza como borrador, visible solo para ti.

Una encuesta de reunión propone huecos en determinados días, en la zona horaria de la sección:

{
	"title": "Reunión de equipo",
	"status": "published",
	"sections": [
		{
			"type": "meeting",
			"properties": { "timezone": "Europe/Madrid", "duration": 60, "location": "Sala 1" },
			"fields": [
				{
					"type": "date",
					"label": "2026-11-02",
					"choices": [{ "label": "09:00-10:00" }, { "label": "14:00-15:00" }]
				},
				{ "type": "date", "label": "2026-11-03", "choices": [{ "label": "09:00-10:00" }] }
			]
		}
	]
}

Asistentes de IA (MCP)

StrawPoll tiene un servidor de Model Context Protocol: así, asistentes de IA como Claude, ChatGPT o Cursor pueden crear encuestas y leer resultados por ti.

• URL del servidor: https://strawpoll.com/mcp (Streamable HTTP)
• Conexión: OAuth. Añade la URL como conector personalizado en tu asistente e inicia sesión en StrawPoll cuando te lo pida; tú decides si autorizas el acceso. Los clientes sin OAuth pueden enviar en su lugar una clave de API mediante X-API-Key o Authorization: Bearer sp_your_key.

Las encuestas creadas por un asistente son tuyas como las demás y usan tus ajustes por defecto para encuestas nuevas. Un asistente puede crear hasta 30 por hora.

Enlaces de encuesta

Los asistentes sin herramientas pueden darte un enlace que abre el editor con la encuesta ya rellenada, lista para revisar y publicar:

https://strawpoll.com/forms/new?title=%C2%BFD%C3%B3nde%20comemos%3F&options=Pizza|Sushi|Tacos

options se divide por | (o repite option=). Añade type=ranking o type=meeting (opciones como 2026-11-03 o 2026-11-03 14:00-15:00, con timezone=Europe/Madrid), multiple=1 para permitir más de una respuesta y other=1 para una respuesta libre.

Endpoints

Cuenta

Formularios

PUT lo sustituye todo: las sections, fields y choices que omitas se eliminan, con sus respuestas. Vuelve a enviar los identificadores de los elementos que quieras conservar para que sus respuestas se mantengan. Los formularios retirados por moderación (deleted, blocked) responden 403.

Borradores y publicación

El editor guarda los cambios como borrador y los publica en un solo paso. Hasta entonces, los participantes siguen viendo el formulario publicado.

Respuestas

Los totales por opción están en el propio formulario: responseCount en cada field y cada choice, y score en las clasificaciones. El objeto fields de una respuesta contiene sus respuestas en la forma descrita en Enviar una respuesta.

Enviar una respuesta

POST/forms/{slug}/submit envía una respuesta igual que la página de votación, aplicando todas las reglas del formulario: calendario, límites, una respuesta por persona, captcha, bloqueo de VPN, códigos y verificación del correo. Los navegadores no necesitan clave; los scripts y otros clientes automatizados tienen que enviar una.

{
	"fields": {
		"<id del campo de opciones>": ["<id del choice>"],
		"<id del campo de clasificación>": [
			"<id del mejor choice>",
			"<id del siguiente choice>",
			"<id del último choice>"
		],
		"<id del campo de fecha>": [{ "choiceId": "<id del choice>", "status": "yes" }],
		"<id del campo sí/no>": "yes",
		"<id del campo de texto>": "Texto libre"
	},
	"name": "Ada",
	"comment": "Opcional",
	"code": "Código único opcional"
}

Un envío correcto devuelve el id de la respuesta. Los rechazos llevan un code: upcoming, closed, full, unavailable, decided, captcha, vpn, code, verify_email, disposable, automated (todos con 403), duplicate (409) y busy (503).

El navegador del participante recibe una cookie strawpoll_session. Con ella, PUT/forms/{slug}/submit y el id de la respuesta cambian esa respuesta, si el formulario permite a los participantes cambiarla.

En los formularios limitados a una respuesta por dirección de correo, verifica primero la dirección con POST/forms/{slug}/verify: envía action: "send" con el email, y luego action: "verify" con el code de 6 cifras que ha recibido el participante.

Códigos e invitaciones

Los mensajes de invitación pueden usar las variables name, form y link entre dobles llaves.

Medios y temas

Migrar desde la Poll API (v3)

La Poll API v3 sigue funcionando, con las mismas rutas, claves y encuestas. La guía de compatibilidad v3 indica qué corresponde a qué.