# Métodos de la API Referencia completa de todos los métodos de la API REST con parámetros, ejemplos y respuestas. ## Métodos de la API Referencia completa de todos los métodos expuestos por la API REST de Formstep. Cada método muestra sus parámetros, ejemplos de solicitud y la forma de las respuestas. > ℹ️ **Un único endpoint, muchos métodos** >

> Todos los métodos son POST https://api.formstep.io/api/v1 con un cuerpo JSON{' '} > {`{"method": "...", "params": {...}}`} y una cabecera Authorization: Bearer fb_.... Consulta{' '} > Descripción general de la API para autenticación y manejo de errores, y{' '} > tokens de API para el token en sí. >

Convenciones

{/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Formularios

{/* ── forms.list ──────────────────────────────────────────────────────────── */} Lista los formularios de un espacio de trabajo. Admite paginación por cursor y búsqueda difusa opcional por nombre. ID del espacio de trabajo. Filtrar por carpeta. Pasa null para obtener solo los formularios en la raíz. Omite para listar todos. Búsqueda difusa por nombre. Los resultados están limitados por limit; no se pagina por cursor. Tamaño de página (1–100). Cursor de paginación de una respuesta anterior. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "forms.list", "params": { "workspaceId": "ws_abc123" } }' ``` ``` { "ok": true, "data": { "items": [ { "id": "frm_abc123", "name": "Contact Form", "folderId": null, "workspaceId": "ws_abc123", "isPublished": true, "publishedAt": 1714041851000, "unpublishedAt": null, "createdAt": 1714041800000, "lastEditedAt": 1714042000000, "emoji": null } ], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` {/* ── forms.get ───────────────────────────────────────────────────────────── */} Obtiene los detalles completos de un formulario, incluidas las preguntas, la portada, el logotipo y una URL de vista previa. ID del formulario. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "forms.get", "params": { "formId": "frm_abc123" } }' ``` ``` { "ok": true, "data": { "id": "frm_abc123", "name": "Event Feedback", "folderId": null, "workspaceId": "ws_abc123", "isPublished": true, "publishedAt": 1714041851000, "unpublishedAt": null, "createdAt": 1714041800000, "lastEditedAt": 1714042000000, "emoji": null, "questions": [ { "id": "q_1", "type": "email-input", "inputType": "email", "title": "Your email", "metadata": null }, { "id": "q_2", "type": "rating-input", "inputType": "rating", "title": "Overall experience", "metadata": { "kind": "rating", "maxStars": 5 } } ], "hasContent": true, "cover": null, "logo": null, "isDeleted": false, "trashedAt": null, "previewUrl": "https://formstep.io/preview/abc..." } } ``` {/* ── forms.create ────────────────────────────────────────────────────────── */} Crea un nuevo formulario vacío. Devuelve el formulario y una URL de vista previa. Nombre del formulario (1–255 caracteres). ID del espacio de trabajo. Coloca el formulario en una carpeta. Omite para crearlo en la raíz del espacio de trabajo. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "forms.create", "params": { "name": "Contact", "workspaceId": "ws_abc123" } }' ``` ``` const res = await fetch('https://api.formstep.io/api/v1', { method: 'POST', headers: { Authorization: `Bearer ${process.env.FORMSTEP_TOKEN}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ method: 'forms.create', params: { name: 'Contact', workspaceId: 'ws_abc123' }, }), }) const { ok, data } = await res.json() ``` ``` import os, requests res = requests.post( "https://api.formstep.io/api/v1", headers={"Authorization": f"Bearer {os.environ['FORMSTEP_TOKEN']}"}, json={ "method": "forms.create", "params": { "name": "Contact", "workspaceId": "ws_abc123", }, }, ) data = res.json() ``` ``` { "ok": true, "data": { "id": "frm_new123", "name": "Contact", "workspaceId": "ws_abc123", "folderId": null, "isPublished": false, "createdAt": 1714041851000, "previewUrl": "https://formstep.io/preview/abc..." } } ``` {/* ── forms.update ────────────────────────────────────────────────────────── */} Actualiza los metadatos del formulario: nombre, carpeta, emoji, portada o logotipo. No actualiza el contenido del formulario (usa las herramientas del editor para eso). ID del formulario. Nuevo nombre del formulario (1–255 caracteres). Mueve el formulario a una carpeta. Pasa null para moverlo a la raíz del espacio de trabajo. Emoji del formulario (máx. 10 caracteres). Pasa null para eliminarlo. Portada. {`{"type": "color", "color": "#ffffff"}`}, {`{"type": "image", "url": "https://...", "offsetY": 50}`}{' '} (offsetY 0–100, 50 por defecto), o {`{"type": "none"}`} para eliminarla. Las URLs de imagen deben ser{' '} http(s) o una URI data:image. Logotipo. {`{"type": "icon", "name": "HeartIcon"}`}, {`{"type": "image", "url": "https://..."}`}, o{' '} {`{"type": "none"}`} para eliminarlo. Los nombres de icono son fijos: QuestionMarkIcon,{' '} ListBulletsIcon, ChartBarIcon, ClockCountdownIcon, HeartIcon,{' '} LightbulbIcon, CheckCircleIcon, MagnifyingGlassIcon, TrendUpIcon,{' '} EnvelopeIcon, PhoneIcon, CalendarIcon, LinkIcon, UsersIcon.

Pasa al menos uno de los cinco campos actualizables. No cambia el contenido del formulario — usa las herramientas del editor de MCP para eso.

``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "forms.update", "params": { "formId": "frm_abc123", "name": "Updated Name", "emoji": "📋" } }' ``` ``` { "ok": true, "data": { "id": "frm_abc123", "name": "Updated Name", "folderId": null, "emoji": "📋" } } ```

cover y logo solo vuelven cuando los enviaste. Un payload que coincidía con el estado actual en todos los campos escalares añade noChange: true.

{/* ── forms.publish ───────────────────────────────────────────────────────── */} Publica un formulario para que pueda recibir respuestas, y congela sus [claves de campo](/es/requests/field-keys) en una nueva instantánea. Idempotente: un formulario ya publicado devuelve éxito con `alreadyPublished: true`, y un formulario despublicado se vuelve a publicar desde su última instantánea. ID del formulario.

Un formulario con bloques de contenido pero sin preguntas se publica con una advertencia. Un formulario sin ningún contenido no se puede publicar. Publicar no crea una URL pública — llama a shareLinks.create para eso.

{/* ── forms.unpublish ─────────────────────────────────────────────────────── */} Pone un formulario fuera de línea. Los respondentes ya no pueden abrirlo. Idempotente — un formulario que no está publicado devuelve `alreadyUnpublished: true`. Reversible con `forms.publish`. ID del formulario. {/* ── forms.delete ────────────────────────────────────────────────────────── */} Mueve un formulario a la papelera. Sus enlaces para compartir activos se revocan, así que sus URLs públicas dejan de funcionar. ID del formulario. > ⚠️ **Restaurar no recupera los enlaces** >

> forms.restore devuelve el formulario, pero los enlaces para compartir que revocó siguen revocados. Genera otros nuevos con{' '} > shareLinks.create. Un formulario que ya está en la papelera devuelve alreadyTrashed: true y conserva su fecha > original de envío a la papelera. >

{/* ── forms.restore ───────────────────────────────────────────────────────── */} Restaura un formulario desde la papelera. ID del formulario. Dónde restaurarlo. Omite para su carpeta original, null para la raíz del espacio de trabajo, o un ID de carpeta.

Un formulario que no está en la papelera devuelve alreadyRestored: true.

{/* ── formSettings.get ────────────────────────────────────────────────────── */} Lee los ajustes de comportamiento de un formulario. ID del formulario.

Devuelve {`{ settings, isDefault, availableEmailDomains, defaultFromAddress, payment }`}. isDefault es true cuando el formulario aún no tiene una fila de ajustes guardada y estás viendo los valores por defecto. availableEmailDomains{' '} contiene los ids de dominio verificados que puedes pasar como emailDomainId, y payment indica si Stripe está conectado (conectarlo es un paso desde el panel).

{/* ── formSettings.update ─────────────────────────────────────────────────── */} Actualiza los ajustes de comportamiento de un formulario. Una actualización parcial: solo se escriben los campos que envías. ID del formulario. language (BCP-47, por defecto "en"), requireAuthentication, showBranding,{' '} captchaEnabled, passwordEnabled, password (4 caracteres o más; una cadena implica{' '} passwordEnabled: true, null elimina el bloqueo). notifyOnSubmission, notificationEmails (array), selfNotificationSubject,{' '} selfNotificationEmailBody, pdfGenerationEnabled, showViewSubmissionButton. Los correos del propietario no son traducibles — escríbelos en el idioma que quieras. respondentNotificationEnabled, respondentNotificationTo (el id de campo de una pregunta de correo, o{' '} null), respondentNotificationSubject, respondentNotificationBody,{' '} respondentNotificationPdfEnabled. respondentReminderEnabled, respondentReminderTo, respondentReminderSubject,{' '} respondentReminderBody, respondentReminderRequiredFieldIds, y reminderSteps — desfases de inactividad como ["1d","3d","1w"], como máximo 5, ordenados y deduplicados al guardar, [] para ninguno. El calendario se aplica tanto a respuestas de enlace público abandonadas como a solicitudes. Pro. redirectUrl (http(s); null o "" lo elimina), redirectQueryParams ( {`[{ paramName, fieldId }]`}), allowAnotherResponse (mutuamente excluyente con una redirección),{' '} maxSubmissionsPerRespondent (0 = sin límite, máx. 1000), editAfterSubmit, maxEdits (máx. 3; 0 significa sin límite en Pro y Business, 3 en Free). draftRetentionDays y submissionRetentionDays (0–36500, null vuelve al valor por defecto). La retención de respuestas es Business, y establecerla elimina cualquier fecha de eliminación fija configurada en el editor. Un id de dominio de correo verificado de formSettings.get, para una dirección De personalizada. null{' '} restablece el remitente por defecto.

Los asuntos y cuerpos son texto plano y aceptan marcadores {`{{variable}}`}; los saltos de línea se convierten en párrafos. Personalizar un asunto o cuerpo de respondente lo hace traducible, así que sus claves aparecen de inmediato en{' '} translations.listEntries.

{/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Respuestas

{/* ── submissions.list ────────────────────────────────────────────────────── */} Lista las respuestas de un formulario, la página más reciente primero, con paginación por cursor. ID del formulario. Incluye respuestas que se empezaron pero nunca se enviaron. Los borradores son una función Pro: en Free solo se listan los envíos completados. Adjunta las traducciones de IA guardadas de las respuestas bajo items[].translation.display, con las mismas claves que{' '} display. items[].answers y items[].display siempre conservan el original. Tamaño de página (1–100). Cursor de paginación de una respuesta anterior. ``` { "ok": true, "data": { "formId": "frm_abc123", "formName": "Event Feedback", "items": [ { "id": "sub_xyz789", "submittedAt": "2026-05-18 18:02:28", "isCompleted": true, "createdAt": "2026-05-18 18:02:19", "answers": { "email": "user@example.com", "plan": "pro", "contacts": [{ "name": "Ada" }, { "name": "Grace" }] }, "display": { "email": "user@example.com", "plan": "Pro", "contacts": "Ada, Grace" } } ], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` > ℹ️ **Las mismas respuestas que webhooks y callbacks** >

> Cada elemento lleva answers indexado por clave de campo y display con > las mismas claves, en texto legible — la forma que llevan un payload de webhook, un{' '} > callback de solicitud y requests.get. Una respuesta de elección es su clave de opción, > un grupo repetitivo un array de instancias. Llama a fields.list para el título y las etiquetas de opción de cada clave. > Este método no devuelve totales. >

{/* ── submissions.pdf ─────────────────────────────────────────────────────── */} Obtiene un enlace al PDF de una respuesta. Construido para el conector de Zapier: solo devuelve un resultado cuando el formulario tiene una integración de Zapier activa configurada para incluir el PDF, y el PDF se conservó. ID del formulario. ID de la respuesta. Debe pertenecer a ese formulario y estar completada. ``` { "ok": true, "data": { "url": "https://api.formstep.io/api/storage/...", "filename": "formstep-submission-sub_xyz789.pdf", "contentType": "application/pdf", "byteLength": 148213 } } ``` {/* ── submissions.sample ──────────────────────────────────────────────────── */} Construye un payload de respuesta de muestra para un formulario, sin ningún dato real. Es exactamente la forma que lleva una entrega de respuesta de enlace público, así que los conectores lo usan para descubrir campos; una respuesta nacida de una solicitud llega a una suscripción como request.completed en su lugar, muestreada por{' '} requests.sample. data.form.snapshotId es la versión publicada actual del formulario, el mismo id que llevan los eventos en vivo, o null mientras el formulario no esté publicado. ID del formulario. ``` { "ok": true, "data": { "id": "evt_example000000000000", "type": "submission.completed", "createdAt": "2026-05-18T19:00:00.000Z", "apiVersion": "2026-09-24", "test": true, "data": { "form": { "id": "frm_abc123", "name": "Event Feedback", "snapshotId": "js7abc123" }, "submission": { "id": "sub_example000000000000", "respondentEmail": "respondent@example.com", "submittedAt": "2026-05-18T19:00:00.000Z", "updatedAt": null, "editCount": 0, "pdfUrl": null, "language": "en" }, "answers": { "your_email": "john@example.com" }, "display": { "your_email": "john@example.com" } } } } ```

La semántica de los campos y del payload está documentada una sola vez, en la{' '} referencia de webhooks.

{/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */} {/* ── shareLinks.list ─────────────────────────────────────────────────────── */} Lista los enlaces compartidos de un formulario. ID del formulario. Incluye los enlaces revocados en el resultado. Tamaño de página (1–100). Cursor de paginación. ``` { "ok": true, "data": { "items": [ { "id": "sl_abc123", "code": "RPjNes52", "url": "https://formstep.io/RPjNes52", "customDomainUrl": null, "formId": "frm_abc123", "createdAt": 1714041851000, "expiresAt": null, "maxClaims": null, "claimedCount": 7, "isRevoked": false, "revokedAt": null, "customDomainId": null, "customSlug": null } ], "availableCustomDomains": [], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` {/* ── shareLinks.create ───────────────────────────────────────────────────── */} Crea un enlace compartido para un formulario. El formulario debe estar publicado primero. ID del formulario. Un formulario despublicado, o que se publicó y luego se despublicó, se rechaza — llama antes a{' '} forms.publish. Vencimiento como marca de tiempo Unix futura en milisegundos. A diferencia de la actualización, aquí no se acepta 0. Número máximo de veces que se puede usar este enlace. Debe ser positivo; usa shareLinks.update para eliminarlo después.

La respuesta es el enlace compartido (con la misma forma que un elemento de shareLinks.list) más{' '} availableCustomDomains, para que puedas continuar con shareLinks.update y asociar uno.

``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "shareLinks.create", "params": { "formId": "frm_abc123", "maxClaims": 100 } }' ``` {/* ── shareLinks.update ───────────────────────────────────────────────────── */} Actualiza un enlace compartido. Puedes cambiar el vencimiento, el número máximo de usos, el dominio personalizado, el slug, o revocar el enlace. ID del enlace compartido. Nueva marca de tiempo de vencimiento en milisegundos. Pasa 0 para eliminar el vencimiento. Nuevo número máximo de usos. Pasa -1 para eliminar el límite. Asocia un dominio personalizado. Pasa null para desasociarlo. Slug de URL personalizado (3–64 caracteres, alfanumérico en minúsculas y guiones). Obligatorio junto con customDomainId; pasa ambos como null para desasociar. login, auth-callback, preview,{' '} payment, api, admin y health están reservados. Establece en true para revocar el enlace de forma permanente. No se puede combinar con otros campos, y no se puede deshacer — esta es la única vía para eliminar un enlace compartido. {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Campos

{/* ── fields.list ─────────────────────────────────────────────────────────── */} Lista todos los campos de la versión publicada actual de un formulario, con la clave para dirigirte a cada uno. Llama a esto antes de `requests.create` en lugar de codificar las claves a mano. Consulta [Claves de campo](/es/requests/field-keys). ID del formulario. Un formulario que nunca se ha publicado todavía no tiene claves de campo y responde con published: false{' '} sin elementos. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "fields.list", "params": { "formId": "j57..." } }' ``` ``` { "ok": true, "data": { "published": true, "items": [ { "key": "company_name", "type": "text", "title": "Company", "required": true, "prefillable": true }, { "key": "company_size", "type": "select", "title": "Company size", "required": false, "prefillable": true, "options": [ { "key": "1_50", "label": "1–50" }, { "key": "51_200", "label": "51–200" } ] }, { "key": "satisfaction", "type": "matrix", "title": "How did we do?", "required": false, "prefillable": true, "rows": [{ "key": "delivery_speed", "label": "Delivery speed" }], "columns": [{ "key": "very_good", "label": "Very good" }, { "key": "poor", "label": "Poor" }] }, { "key": "case_id", "type": "hidden", "title": "Case", "required": false, "prefillable": false, "context": true }, { "key": "total", "type": "number", "title": "Total", "required": false, "prefillable": false, "calculated": true } ], "hasMore": false } } ``` > ℹ️ **Cómo leer los indicadores** >

> context: true es un campo oculto — su valor va en context, nunca en prefill.{' '} > prefillable: false marca un campo al que nadie puede darle un valor (archivo, firma, pago, cita, documentos). Para una > pregunta de elección, envía la clave de la opción, no su etiqueta; una matriz lista sus rows y{' '} > columns del mismo modo y toma {'{ "row_key": "column_key" }'}. calculated: true es un campo > calculado: el formulario calcula su valor, lo vuelves a leer en answers, y nada puede enviarlo. >

Un grupo repetitivo es type: "group" con repeating: true y un array members. Un bloque de Documentos es type: "documents" y lleva documents: [{`{ name }`}], los archivos de autor que todo respondente ya ve.

{/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Solicitudes

Una solicitud asigna un formulario publicado a una persona y te llama de vuelta cuando termina. La guía conceptual está en [Crear una solicitud](/es/requests/creating-requests); esta es la lista de parámetros. {/* ── requests.create ─────────────────────────────────────────────────────── */} Crea una solicitud. Gasta una unidad del cupo mensual del espacio de trabajo, responda o no el destinatario. El formulario publicado a asignar. {`{ email?, name? }`}. Un correo es obligatorio cuando delivery es "email"; en caso contrario solo identifica a la persona en la página de Solicitudes y en sus respuestas. Respuestas iniciales por clave de campo. El destinatario las ve y puede cambiarlas. Claves precompletadas que el destinatario no puede cambiar. Cada clave aquí también debe aparecer en prefill, y un campo obligatorio bloqueado debe estar precompletado con un valor no vacío. Valores para los campos ocultos del formulario, por clave de campo. De confianza, inmutables, y devueltos en el callback. Una clave desconocida se rechaza con UNKNOWN_FIELD_KEY. Tu propia contabilidad. Nunca llega al formulario; vuelve en los callbacks y las lecturas. Uno de los idiomas publicados del formulario. Por defecto, el idioma predeterminado del formulario. "email" para que Formstep envíe la invitación (necesita un correo del destinatario, y Pro o Business o una de las 10 invitaciones gratis de una cuenta Free), o "none" para entregar tú mismo el enlace. Anula el calendario de recordatorios del formulario para esta solicitud. Un array vacío desactiva los recordatorios. Milisegundos desde epoch. Por defecto, 30 días; 365 días es el máximo. Adónde envía Formstep el callback en POST cuando la solicitud termina. Solo HTTPS, y el host debe resolver a una dirección pública. Tu propio id para esta solicitud. Filtrable en requests.list. Repetirla con el mismo cuerpo devuelve la solicitud original con deduplicated: true. Un cuerpo distinto se rechaza. Las claves viven 30 días. Genera el enlace en uno de tus dominios personalizados. Solo en la API REST. {`[{ documentId, field?, name? }]`} — archivos entregados a este destinatario, subidos antes con{' '} documents.create. Un ensayo: no se envía nada por correo, el callback lleva "test": true, y el envío no cuenta en ningún sitio. El enlace se cierra en un plazo de 24 horas, y en Free un workspace puede crear 10 solicitudes de prueba al día. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "requests.create", "params": { "formId": "j57...", "recipient": { "email": "ada@acme.com", "name": "Ada" }, "prefill": { "company_name": "Acme" }, "readonly": ["company_name"], "context": { "case_id": "CASE-9" }, "delivery": "email", "externalId": "run-42", "callbackUrl": "https://automation.example/webhook/resume-abc", "idempotencyKey": "run-42" } }' ``` ``` { "ok": true, "data": { "id": "kd7...", "status": "pending", "url": "https://form.formstep.io/r/rq_...", "deliveryStatus": "queued", "expiresAt": 1794787200000, "createdAt": 1789379200000, "externalId": "run-42", "deduplicated": false } } ``` > ⚠️ **Guarda la url** >

> url lleva el token de un solo uso. requests.get normalmente puede reconstruirla, pero vuelve como{' '} > null para una solicitud creada antes de que el despliegue tuviera una clave de token de solicitud. Si entregas el enlace tú > mismo, guárdalo al crearlo. >

deliveryStatus es not_requested hasta que se pone en cola una invitación, luego queued →{' '} sent o failed, y bounced en cuanto el proveedor de correo reporta un rebote definitivo o una queja.

{/* ── requests.get ────────────────────────────────────────────────────────── */} Obtén una solicitud completa: estado, resultado, lo que se precompletó, su cronología y — una vez completada — answers y{' '} display indexados por clave de campo, los mismos dos mapas que lleva el callback. ID de la solicitud. ``` { "ok": true, "data": { "id": "kd7...", "formId": "j57...", "status": "completed", "outcome": "approve", "isTest": false, "recipient": { "email": "ada@acme.com", "name": "Ada" }, "language": "en", "externalId": "run-42", "metadata": null, "context": { "case_id": "CASE-9" }, "prefill": { "company_name": "Acme" }, "readonlyKeys": ["company_name"], "delivery": "email", "deliveryStatus": "sent", "hasCallback": true, "callbackFailedAt": null, "submissionId": "kp2...", "url": "https://form.formstep.io/r/rq_...", "answers": { "company_name": "Acme", "decision": "approve" }, "display": { "company_name": "Acme", "decision": "Approve" }, "timeline": [ { "id": "kd7...:created", "type": "created", "at": 1789379200000 }, { "id": "kd7...:completed", "type": "completed", "at": 1789465600000 } ], "expiresAt": 1794787200000, "completedAt": 1789465600000 } } ``` > ℹ️ **outcome frente a status** >

> status dice si la solicitud terminó; outcome dice qué decidió el destinatario — approve,{' '} > decline, changes, o null en cualquier caso que no sea una solicitud completada cuyo destinatario > eligió una de las tres — incluido un formulario sin pregunta de decisión. La URL del > callback nunca se devuelve; hasCallback solo dice si hay una configurada. >

El ejemplo anterior está recortado. Una respuesta completa también lleva workspaceId, formSnapshotId,{' '} createdVia, documents, reminderStep, remindersSent, reminderDueAt,{' '} dataPurgedAt, y el resto de las marcas de tiempo (updatedAt, openedAt, startedAt,{' '} lastActivityAt, expiredAt, canceledAt, canceledBy, cancelReason).

Dos campos te dicen cuándo la copia que tienes delante es la única copia. callbackFailedAt está establecido mientras el callback de esta solicitud se ha quedado sin intentos, y se limpia en cuanto uno llega o lo repites. dataPurgedAt se establece una vez que la retención elimina la solicitud: context, prefill y metadata vuelven vacíos, readonlyKeys y documents son [], y submissionId, answers y{' '} display son null.

timeline se deriva, del más antiguo al más reciente. Cada entrada tiene un id, un at, y un{' '} type — created, invitation, reminder, opened, started,{' '} completed, expired, canceled, callback. Las entradas de entrega añaden{' '} deliveryStatus y attemptCount, y los callbacks añaden eventType. Las filas de entrega se conservan 30 días, así que las cronologías más antiguas se reducen a las marcas de tiempo.

{/* ── requests.list ───────────────────────────────────────────────────────── */} Lista las solicitudes de un espacio de trabajo o de un formulario, las más recientes primero. Las solicitudes de prueba se omiten a menos que las pidas. Limita a un espacio de trabajo. Da esto o formId. Limita a un formulario. pending, completed, expired, o canceled. approve, decline, o changes. Implica solo solicitudes completadas. Tu propio id, para encontrar la solicitud que creó una ejecución. Incluye las solicitudes creadas con test: true. Tamaño de página (1–100). Cursor de paginación de una respuesta anterior. ``` { "ok": true, "data": { "items": [ { "id": "kd7...", "formId": "j57...", "status": "pending", "outcome": null, "recipient": { "email": "ada@acme.com", "name": "Ada" }, "externalId": "run-42", "deliveryStatus": "sent", "expiresAt": 1794787200000, "createdAt": 1789379200000 } ], "nextCursor": null, "hasMore": false } } ```

Los elementos de la lista llevan los mismos campos que requests.get salvo url, answers,{' '} display y timeline, y cada uno lleva isTest. Da workspaceId o formId — no dar ninguno es 400 VALIDATION_ERROR con motivo SCOPE_REQUIRED. outcome tiene prioridad sobre{' '} status, ya que solo una solicitud completada tiene un veredicto.

{/* ── requests.cancel ─────────────────────────────────────────────────────── */} Retira una solicitud pendiente. El enlace deja de funcionar, el destinatario ve un aviso de retirada, y se dispara un callback `request.canceled`. ID de la solicitud. Tu nota sobre el motivo, guardada en la solicitud y enviada en el callback. {/* ── requests.remind ─────────────────────────────────────────────────────── */} Envía un correo al destinatario ahora, sin tocar el calendario de recordatorios. Necesita un correo del destinatario y un plan Pro o Business. ID de la solicitud. Debe seguir pendiente, y no ser una solicitud de prueba.

Se aplican dos límites: al menos 10 minutos entre recordatorios manuales, y como máximo 8 recordatorios por solicitud en total, manuales y programados juntos. El calendario automático no se toca — reminderStep y reminderDueAt quedan como estaban.

{/* ── requests.replayCallback ─────────────────────────────────────────────── */} Reenvía el callback que disparó una solicitud al terminar — mismo payload, mismo id de evento, para que un receptor que ya lo procesó pueda deduplicarlo. Úsalo tras arreglar un endpoint que fallaba. ID de la solicitud. Debe estar completada, expirada o cancelada. ``` { "ok": true, "data": { "dispatchId": "kf9...", "eventId": "evt_kf9..." } } ``` {/* ── requests.sample ─────────────────────────────────────────────────────── */} Construye un evento de solicitud de muestra para un formulario, sin ninguna solicitud real. Es exactamente el envoltorio que recibe una suscripción a request\_\* creada con webhooks.create, así que los conectores lo usan para descubrir campos. Una muestra completada lleva las mismas respuestas de ejemplo que muestra{' '} submissions.sample; una muestra expirada o cancelada lleva solo el bloque request. ID del formulario. Qué final muestrear, en la grafía de webhooks.create. El type del envoltorio es la forma con puntos. ``` { "ok": true, "data": { "id": "evt_example000000000000", "type": "request.completed", "createdAt": "2026-05-18T19:00:00.000Z", "apiVersion": "2026-09-24", "test": true, "data": { "request": { "id": "req_example000000000000", "externalId": "order-1234", "status": "completed", "language": "en", "recipient": { "email": "recipient@example.com", "name": "Sample Recipient" }, "metadata": { "source": "sample" }, "context": {}, "createdAt": "2026-05-18T18:00:00.000Z", "completedAt": "2026-05-18T19:00:00.000Z" }, "form": { "id": "frm_abc123", "name": "Event Feedback", "snapshotId": "js7abc123" }, "submission": { "id": "sub_example000000000000", "respondentEmail": "respondent@example.com", "submittedAt": "2026-05-18T19:00:00.000Z", "updatedAt": null, "editCount": 0, "pdfUrl": null, "language": "en" }, "answers": { "your_email": "john@example.com" }, "display": { "your_email": "john@example.com" } } } } ```

El bloque request y el resultado están documentados en la página de callbacks; la mitad de la respuesta en la referencia de webhooks. Los ids de muestra son los marcadores fijos que se muestran arriba y test es true, así que un receptor puede distinguir una muestra de un evento real.

{/* ── documents.create ────────────────────────────────────────────────────── */} Reserva una subida para un archivo que entregarás a un destinatario a través del [bloque de Documentos](/es/building-forms/documents-block) del formulario. Los bytes nunca pasan por esta API: obtienes un `PUT` prefirmado, subes el archivo, y `requests.create` verifica el objeto antes de que la solicitud exista. El formulario cuyo bloque de Documentos mostrará el archivo. Limita la subida a ese espacio de trabajo. Nombre visible que ve el destinatario (1–200 caracteres). Se puede anular por solicitud. application/pdf o un tipo de imagen: image/png, image/jpeg, image/webp,{' '} image/gif, image/svg+xml, image/avif, image/bmp, image/tiff. No se aceptan documentos de Office. Longitud exacta en bytes. Máximo 25 MB (26.214.400). Digest hexadecimal de los bytes. Se verifica después de subir el archivo, cuando se proporciona. ``` { "ok": true, "data": { "id": "kn7...", "name": "Lease contract draft", "contentType": "application/pdf", "size": 412000, "uploadUrl": "https://...", "expiresAt": 1792198800000 } } ```

Haz un PUT de los bytes en bruto a uploadUrl antes de que pase una hora, con Content-Type ajustado al tipo que declaraste, y luego referencia el id desde requests.create:

``` { "method": "requests.create", "params": { "formId": "j57...", "documents": [ { "documentId": "kn7...", "name": "Your lease contract" }, { "documentId": "kn8...", "field": "attachments" } ] } } ```

Todo fallo aquí es 400 VALIDATION_ERROR con un details.reason: DOCUMENT_TYPE_NOT_ALLOWED,{' '} DOCUMENT_TOO_LARGE, INVALID_DOCUMENT_NAME o INVALID_DOCUMENT_SHA256 de este método, y{' '} DOCUMENT_NOT_FOUND, DOCUMENT_NOT_UPLOADED (te saltaste el PUT), DOCUMENT_INVALID,{' '} INVALID_DOCUMENT_TARGET, DOCUMENTS_TOO_LARGE o DOCUMENTS_TOO_MANY de requests.create.

{/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Webhooks

{/* ── webhooks.list ───────────────────────────────────────────────────────── */} Lista las suscripciones de webhook de un formulario. ID del formulario. ``` { "ok": true, "data": { "items": [ { "subscriptionId": "int_abc123", "formId": "frm_abc123", "provider": "zapier", "targetUrl": "https://hooks.zapier.com/...", "eventType": "submission_created", "status": "active", "createdAt": 1714041851000 } ], "hasMore": false } } ``` {/* ── webhooks.create ─────────────────────────────────────────────────────── */} Suscribe una URL a eventos del formulario: respuestas nuevas o abandonadas, o solicitudes del formulario al terminar. La URL debe usar HTTPS. ID del formulario. URL HTTPS para recibir los payloads del webhook. A qué herramienta pertenece la suscripción. Es una etiqueta para tu propia contabilidad — no hay ninguna app de marketplace que instalar, y todos los proveedores se comportan igual. Tipo de evento al que suscribirse. Los tres tipos submission_* entregan el payload de la respuesta:{' '} submission_created una primera respuesta, submission_updated una edición del respondente, y{' '} submission_abandoned un borrador inactivo. Los tres tipos request_* entregan el{' '} evento de solicitud correspondiente cada vez que una solicitud del formulario termina de ese modo, firmado con el secreto de esta suscripción; las solicitudes de prueba no llegan a ninguna suscripción. Obligatorio cuando eventType es submission_abandoned; rechazado para cualquier otro tipo. Secreto de firma HMAC opcional, 32–255 caracteres. Cuando se proporciona, las entregas incluyen X-Formstep-Signature. El secreto se guarda pero la API nunca lo devuelve. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "webhooks.create", "params": { "formId": "frm_abc123", "targetUrl": "https://hooks.zapier.com/hooks/catch/...", "provider": "zapier", "eventType": "submission_created", "signingSecret": "whsec_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef" } }' ``` ``` { "ok": true, "data": { "subscriptionId": "int_new123", "formId": "frm_abc123", "provider": "zapier", "targetUrl": "https://hooks.zapier.com/hooks/catch/...", "eventType": "submission_created" } } ```

Las suscripciones de respuestas abandonadas devuelven el idleWindow elegido tanto en webhooks.create como en{' '} webhooks.list. Cualquier otra suscripción lo omite.

Una suscripción de solicitudes escucha los mismos eventos que un callback, pero como su propia entrega: su propio id de evento, su propia firma y su propio presupuesto de cinco reintentos, tras el cual la suscripción se pausa. Una solicitud creada con callbackUrl en un formulario con una suscripción request_completed se dispara entonces dos veces, una a cada receptor. requests.replayCallback reenvía solo el callback. Usa{' '} requests.sample para ver el payload antes de que ninguna solicitud haya terminado.

{/* ── webhooks.delete ─────────────────────────────────────────────────────── */} Elimina una suscripción de webhook. ID de suscripción de webhooks.list o webhooks.create. ``` { "ok": true, "data": { "subscriptionId": "int_abc123", "deleted": true } } ``` {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Analíticas

{/* ── analytics.get ───────────────────────────────────────────────────────── */} Obtiene métricas de analíticas agregadas de un formulario. Admite filtros por rango de fechas, dispositivo, fuente de tráfico y país. Las analíticas son una función Pro, y la regla sigue el plan del **propietario** del espacio de trabajo, igual que la pestaña Analíticas del panel. Si el propietario no tiene Pro, la llamada devuelve `UPGRADE_REQUIRED` — también para el historial registrado cuando sí lo tenía. Un miembro Free en el espacio de un propietario Pro sí recibe los datos. ID del formulario. Inicio del rango de fechas como marca de tiempo Unix en milisegundos. Debe ser menor o igual que to cuando ambos están establecidos. Fin del rango de fechas como marca de tiempo Unix en milisegundos. Omite ambos para todo el historial — period vuelve entonces como {`{ "from": null, "to": null }`}. Filtrar por tipo de dispositivo. Filtrar por fuente de tráfico (p. ej. "Direct", "Google"). Filtrar por código de país de 2 letras (p. ej. "US", "DE"). Devuelve también los eventos de analíticas anonimizados detrás de las métricas, para tu propio análisis. Sin ids de visitante.

Las tasas son números de 0 a 100, los recuentos son enteros, y totalEvents es el número de filas de eventos en bruto antes de la deduplicación en visitantes únicos.

``` { "ok": true, "data": { "formId": "frm_abc123", "period": { "from": null, "to": null }, "totalEvents": 17, "metrics": { "views": 7, "uniqueVisitors": 7, "engaged": 6, "submissions": 4, "engagementRate": 86, "completionRate": 57, "bounceRate": 14 }, "breakdown": { "byBrowser": { "Chrome": 17 }, "byCountry": { "US": 10, "DE": 7 }, "byDevice": { "desktop": 14, "mobile": 3 }, "bySource": { "Direct": 12, "Google": 5 } } } } ``` {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Espacios de trabajo

{/* ── workspaces.list ─────────────────────────────────────────────────────── */} Lista los espacios de trabajo a los que puede acceder tu token. Sin parámetros. Un token de API está vinculado a un espacio de trabajo, así que esto devuelve exactamente ese — incluso si tu cuenta pertenece a varios. ``` { "ok": true, "data": { "items": [ { "id": "ws_abc123", "name": "Acme Inc", "createdAt": 1714041800000, "role": "owner" } ], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` {/* ── workspaces.createInvite ─────────────────────────────────────────────── */} Crea un enlace de invitación para un espacio de trabajo. ID del espacio de trabajo. Vencimiento como marca de tiempo Unix futura en milisegundos. Número máximo de veces que se puede usar la invitación. ``` { "ok": true, "data": { "id": "inv_abc123", "workspaceId": "ws_abc123", "code": "aBcDeFgH", "expiresAt": null, "maxUses": null, "uses": 0, "createdAt": 1714041851000 } } ``` {/* ── workspaces.getInvite ────────────────────────────────────────────────── */} Obtiene una invitación a un espacio de trabajo. Devuelve la misma forma que `workspaces.createInvite`. ID de la invitación. {/* ── workspaces.updateInvite ─────────────────────────────────────────────── */} Actualiza una invitación existente a un espacio de trabajo. Proporciona al menos uno de expiresAt o maxUses, o la llamada se rechaza. Devuelve la invitación actualizada. ID de la invitación. Nueva marca de tiempo de vencimiento en milisegundos. Nuevo límite de usos máximos. {/* ── workspaces.revokeInvite ─────────────────────────────────────────────── */} Revoca permanentemente una invitación a un espacio de trabajo. ID de la invitación. ``` { "ok": true, "data": { "inviteId": "inv_abc123", "revoked": true } } ``` {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Carpetas

{/* ── folders.list ────────────────────────────────────────────────────────── */} Lista las carpetas de un espacio de trabajo. ID del espacio de trabajo. Tamaño de página (1–100). Cursor de paginación. ``` { "ok": true, "data": { "items": [ { "id": "fld_abc123", "name": "Customer Feedback", "workspaceId": "ws_abc123", "parentId": null, "createdAt": 1714041800000 } ], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` {/* ── folders.create ──────────────────────────────────────────────────────── */} Crea una carpeta en un espacio de trabajo. Es idempotente: devuelve la carpeta existente si ya existe una con el mismo nombre. ID del espacio de trabajo. Nombre de la carpeta (1–255 caracteres). ID de la carpeta padre para anidar. Omite para el nivel raíz. ``` { "ok": true, "data": { "id": "fld_new123", "name": "Customer Feedback", "workspaceId": "ws_abc123", "parentId": null, "createdAt": 1714041851000, "alreadyExisted": false } } ``` {/* ── folders.update ──────────────────────────────────────────────────────── */} Renombra una carpeta o la mueve a un padre diferente. ID de la carpeta. Nuevo nombre de la carpeta (1–255 caracteres). Nueva carpeta padre. Pasa null para moverla a la raíz. {/* ── folders.delete ──────────────────────────────────────────────────────── */} Elimina permanentemente una carpeta y todo su contenido (subcarpetas y formularios). ID de la carpeta. > ⚠️ **Operación destructiva** >

Esto elimina permanentemente todas las subcarpetas y formularios dentro de la carpeta. Esta acción no se puede deshacer.

``` { "ok": true, "data": { "folderId": "fld_abc123", "deletedFolderIds": ["fld_abc123"], "deletedFormIds": ["frm_in_folder"], "message": "Folder and 1 form deleted." } } ```

Traducciones

{/* ── translations.listLanguages ──────────────────────────────────────────── */} Lista todos los idiomas configurados en un formulario. ID del formulario. ``` { "ok": true, "data": { "formId": "frm_abc123", "items": [ { "language": "es", "completion": { "total": 15, "current": 12, "outdated": 2, "missing": 1, "suggested": 0 }, "lastUpdatedAt": 1714041851000 } ], "nextCursor": null, "hasMore": false, "canPaginate": false } } ``` {/* ── translations.addLanguage ────────────────────────────────────────────── */} Registra un idioma en un formulario. Cualquier otro método de traducción falla con `404 NOT_FOUND` hasta que lo hagas. ID del formulario. Etiqueta de idioma BCP-47 (p. ej. "es", "pt-BR"). ``` { "ok": true, "data": { "formId": "frm_abc123", "language": "es", "rowId": "tl_new123" } } ``` {/* ── translations.removeLanguage ─────────────────────────────────────────── */} Elimina un idioma y todas sus traducciones de un formulario. ID del formulario. Etiqueta de idioma BCP-47. {/* ── translations.listEntries ────────────────────────────────────────────── */} Lista cada clave de origen para un idioma en un formulario, con su estado actual. Así es como descubres los valores de `key` que acepta `translations.setEntry`. ID del formulario. Etiqueta de idioma BCP-47. Debe estar ya en el formulario. ``` { "ok": true, "data": { "formId": "frm_abc123", "language": "es", "completion": { "total": 15, "current": 12, "outdated": 2, "missing": 1, "suggested": 0 }, "items": [ { "key": "block_q_1.title", "status": "current", "value": "[{\"text\":\"Tu correo electrónico\"}]", "sourceFragment": "[{\"text\":\"Your email\"}]", "updatedAt": 1714041851000, "block": { "id": "q_1", "type": "email-input", "label": "Your email" } } ], "hasMore": false } } ```

status es missing (nada guardado), current, outdated (el origen cambió desde entonces), o suggested (una sugerencia de IA preparada pero no aceptada). Las claves cubren el contenido del formulario ( block_<id>.*) y, una vez que un autor las ha personalizado, los correos de confirmación y recordatorio del respondente (email.confirmation.*, email.reminder.*).

{/* ── translations.setEntry ───────────────────────────────────────────────── */} Establece una entrada de traducción individual. El idioma debe haberse agregado previamente con translations.addLanguage. ID del formulario. Etiqueta de idioma BCP-47. Una clave de translations.listEntries. No la construyas a mano. El fragmento traducido, en formato JSON-string. Su estructura de marcas debe coincidir con la del fragmento de origen. ``` curl -X POST https://api.formstep.io/api/v1 \ -H "Authorization: Bearer fb_..." \ -H "Content-Type: application/json" \ -d '{ "method": "translations.setEntry", "params": { "formId": "frm_abc123", "language": "es", "key": "block_q_1.title", "value": "[{\"text\":\"Tu correo electrónico\"}]" } }' ``` > ⚠️ **Aquí las escrituras son en vivo** >

> La API no tiene un paso de borrador y luego publicación: un setEntry o deleteEntry llega a los respondentes de > inmediato. El panel y las herramientas de traducción de MCP usan un borrador en su lugar. >

Devuelve {`{ formId, language, key }`}.

{/* ── translations.deleteEntry ────────────────────────────────────────────── */} Elimina una entrada de traducción individual, revirtiendo esa clave al idioma predeterminado del formulario. Idempotente. Cuando desaparece la última entrada de un idioma, ese idioma deja de figurar entre los idiomas publicados del formulario. ID del formulario. Etiqueta de idioma BCP-47. Clave de traducción a eliminar. {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Cuenta

{/* ── me.get ──────────────────────────────────────────────────────────────── */} Obtiene información sobre el usuario autenticado. ``` { "ok": true, "data": { "id": "usr_abc123", "email": "you@example.com", "name": "Jane Doe" } } ``` {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Meta

Lista, ordenados, todos los nombres de métodos que sirve este despliegue. La respuesta autorizada cuando esta página y el servidor no coinciden. ``` { "ok": true, "data": { "methods": [ "methods.list", "analytics.get", "folders.create", "folders.delete", "folders.list", "folders.update", "formSettings.get", "formSettings.update", "forms.create", "forms.delete", "forms.get", "forms.list", "..." ] } } ``` {/* ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ */}

Referencia de errores

Cada respuesta de error tiene la misma forma. El conjunto de `code` de nivel superior es cerrado a propósito: un nuevo modo de fallo nunca añade un código, añade un `reason`. Decide según `code` para el resultado a nivel HTTP y según `details.reason` para la solución. ``` { "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "No field with key \"company\" on this form.", "details": { "reason": "UNKNOWN_FIELD_KEY", "field": "prefill.company", "validKeys": ["company_name", "contacts"] } } } ```

details está presente siempre que el servidor pueda nombrar la causa. Además de reason, puede llevar{' '} field (el parámetro causante, con puntos para el anidamiento), validKeys, validValues (los{' '} values de opción que acepta una pregunta de elección), expectedType, feature (en{' '} UPGRADE_REQUIRED), y retryAfterMs (en una llamada limitada). Los motivos de la superficie de solicitudes se listan junto a cada método más arriba.

Estos son todos los códigos:

Parámetros inválidos o ausentes en la solicitud. Token de API ausente o inválido. El token no tiene acceso al recurso solicitado. El recurso no existe. Nombre de método desconocido. Usa methods.list para ver los métodos disponibles. El recurso no está en un estado que permita esta llamada — una solicitud que ya no está pendiente, una clave de idempotencia reutilizada con un cuerpo distinto. Más de 120 llamadas por minuto con este token, más de 60 llamadas a requests.create por minuto, o demasiadas autenticaciones fallidas desde esta IP. La función requiere un nivel de suscripción superior, el espacio de trabajo ha gastado su asignación mensual (motivo{' '} MONTHLY_ALLOWANCE_REACHED), o una cuenta Free ha gastado sus 10 invitaciones gratis (motivo{' '} FREE_INVITATIONS_USED). Error inesperado del servidor. Inténtalo de nuevo más tarde.

Próximos pasos

- [Tokens de API](/es/developers/api-tokens) — Crea y gestiona tokens - [Servidor MCP](/es/developers/mcp-server) — Usa Formstep desde agentes de IA - [Referencia de webhooks](/es/developers/webhooks-reference) — Esquema de payload y firma