NueForm

API de Formularios

Crea, obtén, actualiza, elimina, publica y duplica formularios.

La API de Formularios te permite gestionar programáticamente tus formularios de NueForm. Puedes listar, crear, obtener, actualizar, eliminar, publicar, despublicar y duplicar formularios.

Todos los cuerpos de solicitud y respuesta utilizan nombres de campo en snake_case.

Endpoints
GET/api/v1/formsPOST/api/v1/formsGET/api/v1/forms/:idPUT/api/v1/forms/:idDELETE/api/v1/forms/:idPOST/api/v1/forms/:id/publishDELETE/api/v1/forms/:id/publishPOST/api/v1/forms/:id/duplicate

Listar Formularios

GET/api/v1/forms

Devuelve una lista paginada de formularios a los que el usuario autenticado tiene acceso, incluyendo formularios personales y formularios de equipos a los que pertenece el usuario.

Parámetros de Consulta

pageinteger

Número de página (por defecto: 1)

per_pageinteger

Resultados por página (por defecto: 50)

searchstring

Filtrar formularios por título (coincidencia parcial insensible a mayúsculas)

team_idstring

Solo devolver formularios que pertenezcan a este equipo

publishedboolean

Filtrar por estado de publicación (true o false)

Respuesta

json
{
  "forms": [
    {
      "id": "665a1b2c3d4e5f6a7b8c9d0e",
      "title": "Customer Feedback Survey",
      "description": "Quarterly satisfaction survey for Q1 2026",
      "slug": "a1b2c3d4e5f6",
      "published": true,
      "created_at": "2026-01-15T10:30:00.000Z",
      "updated_at": "2026-02-20T14:22:00.000Z",
      "theme_color": "#6366f1",
      "background_color": "#0a0a0a",
      "response_count": 142,
      "team": {
        "id": "665b2c3d4e5f6a7b8c9d0e1f",
        "name": "Marketing"
      }
    }
  ],
  "total": 24,
  "page": 1,
  "per_page": 50
}

Ejemplos de Código

bash
curl -X GET "https://api.nueform.io/api/v1/forms?page=1&per_page=10&published=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Crear Formulario

POST/api/v1/forms

Crea un nuevo formulario. Opcionalmente puedes incluir un array de preguntas para crear junto con el formulario.

Cuerpo de Solicitud

titlestring

Título del formulario (no puede estar vacío)

descriptionstring

Descripción del formulario

team_idstring

Asignar el formulario a un equipo (requiere permiso create_forms)

publishedboolean

Establécelo en true para publicar el formulario justo después de crearlo. La publicación ejecuta las mismas comprobaciones que Publicar Formulario. Si alguna comprobación falla, el formulario se crea igualmente como borrador: la respuesta es 201 con published: false y un objeto publish_error (reason, message, question_ids, upgrade_required). No vuelvas a crear el formulario: corrige el problema y luego llama a Publicar Formulario. Por defecto: false (borrador)

theme_colorstring

Color primario del tema (hex, por defecto: #6366f1)

background_colorstring

Color de fondo (hex, por defecto: #0a0a0a)

text_colorstring

Color del texto de la pregunta (hex)

answer_text_colorstring

Color del texto de entrada de respuesta (hex)

placeholder_colorstring

Color del placeholder del campo de entrada (hex)

button_colorstring

Color de fondo del botón (hex)

button_text_colorstring

Color del texto del botón (hex)

title_colorstring

Color del texto del título (hex)

description_colorstring

Color del texto de la descripción (hex)

option_text_colorstring

Color del texto de opciones de selección (hex)

indicator_bg_colorstring

Color de fondo del indicador de paso (hex)

indicator_text_colorstring

Color del texto del indicador de paso (hex)

font_familystring

Familia tipográfica de la pregunta

font_family_answerstring

Familia tipográfica del campo de respuesta

font_family_buttonstring

Familia tipográfica del botón

font_family_descriptionstring

Familia tipográfica de la descripción

font_family_optionstring

Familia tipográfica de opciones de selección

font_family_indicatorstring

Familia tipográfica del indicador de paso

question_font_sizestring

Tamaño de fuente de la pregunta (ej., "24px")

custom_cssstring

CSS personalizado inyectado en el renderizador del formulario

show_progress_barboolean

Mostrar barra de progreso (por defecto: true)

branding_logo_urlstring

URL para el logo de marca

branding_footer_textstring

Texto personalizado del pie de página

hide_brandingboolean

Ocultar marca de NueForm (por defecto: false)

auto_translateboolean

NueLingo — traduce el formulario publicado bajo demanda a cualquier idioma soportado para los encuestados (Pro+; se guarda como false en otros planes). Requiere un idioma predeterminado; surte efecto al publicar.

top_logo_urlstring

URL para un logo mostrado en la parte superior del formulario

top_logo_sizestring

Tamaño del logo superior (ej., "120px")

top_logo_alignmentstring

Alineación del logo superior ("left", "center", "right")

top_logo_cssstring

CSS personalizado para el logo superior

watermark_cssstring

CSS personalizado para la marca de agua

welcome_titlestring

Título de la pantalla de bienvenida

welcome_descriptionstring

Descripción de la pantalla de bienvenida

welcome_button_textstring

Texto del botón de la pantalla de bienvenida (por defecto: "Start")

thank_you_titlestring

Título de la pantalla de agradecimiento (por defecto: "Thank you!")

thank_you_descriptionstring

Descripción de la pantalla de agradecimiento

modestring

Modo del formulario: "standard", "knowledge_quiz", "lead_qualification", "match_quiz" (por defecto: "standard")

quiz_settingsobject

Configuración del quiz (para modos de quiz)

variablesobject

Variables a nivel de formulario para lógica

start_logic_jumpsarray

Reglas de salto lógico aplicadas al inicio del formulario

webhook_urlstring

URL para recibir POST en el envío (requiere plan Pro)

limit_one_responseboolean

Limitar a una respuesta por visitante (por defecto: false)

incremental_submissionboolean

Guardar respuestas incrementalmente a medida que el encuestado progresa (por defecto: false)

questionsarray

Array de objetos de pregunta a crear (ver abajo)

Ejemplo de Solicitud

json
{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "type": "short_text",
      "title": "What is your name?",
      "required": true
    },
    {
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "required": true,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      }
    },
    {
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "required": true,
      "properties": {
        "steps": 5,
        "shape": "star"
      }
    }
  ]
}

Respuesta

Devuelve el objeto del formulario creado con todas las preguntas:

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": false,
  "created_at": "2026-02-28T12:00:00.000Z",
  "updated_at": "2026-02-28T12:00:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "show_progress_bar": true,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d002",
      "type": "multiple_choice",
      "title": "How did you hear about us?",
      "description": null,
      "required": true,
      "order": 1,
      "properties": {
        "choices": [
          { "label": "Search engine" },
          { "label": "Social media" },
          { "label": "Friend or colleague" },
          { "label": "Other" }
        ],
        "allow_multiple": false
      },
      "logic_jumps": [],
      "validations": {}
    },
    {
      "id": "66a1b2c3d4e5f6a7b8c9d003",
      "type": "rating",
      "title": "How would you rate your overall experience?",
      "description": null,
      "required": true,
      "order": 2,
      "properties": {
        "steps": 5,
        "shape": "star"
      },
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Ejemplos de Código

bash
curl -X POST "https://api.nueform.io/api/v1/forms" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Customer Feedback Survey",
    "description": "Help us improve our product",
    "questions": [
      {
        "type": "short_text",
        "title": "What is your name?",
        "required": true
      }
    ]
  }'

Obtener Formulario

GET/api/v1/forms/:id

Obtiene un formulario individual por ID, incluyendo todas las preguntas ordenadas por su posición.

Parámetros de Ruta

idstring

El ID del formulario

Respuesta

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "description": "Help us improve our product",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "created_at": "2026-01-15T10:30:00.000Z",
  "updated_at": "2026-02-20T14:22:00.000Z",
  "theme_color": "#2563eb",
  "background_color": "#ffffff",
  "text_color": null,
  "answer_text_color": null,
  "placeholder_color": null,
  "button_color": null,
  "button_text_color": null,
  "font_family": null,
  "question_font_size": null,
  "custom_css": null,
  "show_progress_bar": true,
  "incremental_submission": false,
  "limit_one_response": false,
  "welcome_title": "We value your feedback",
  "welcome_description": "This survey takes about 3 minutes.",
  "welcome_button_text": "Let's go",
  "thank_you_title": "Thank you!",
  "thank_you_description": "Your feedback helps us build a better product.",
  "branding_logo_url": null,
  "branding_footer_text": null,
  "hide_branding": false,
  "auto_translate": false,
  "mode": "standard",
  "webhook_url": null,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "response_count": 142,
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your name?",
      "description": null,
      "required": true,
      "order": 0,
      "properties": {},
      "logic_jumps": [],
      "validations": {}
    }
  ]
}

Ejemplos de Código

bash
curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Actualizar Formulario

PUT/api/v1/forms/:id

Actualiza los campos de un formulario y sincroniza sus preguntas. Cuando incluyes un array de questions, NueForm:

  • Actualiza preguntas existentes (coincidencia por id)
  • Crea nuevas preguntas (sin id o id no reconocido)
  • Elimina preguntas que existen en el formulario pero no están presentes en el array

Si el formulario está actualmente publicado, la marca has_unpublished_changes se establece automáticamente en true: tus cambios se guardan como borrador y los encuestados siguen viendo la versión publicada hasta que vuelvas a publicar.

published cambia el estado del formulario en lugar de guardarse como un campo:

  • En un formulario en borrador, published: true lo publica después de guardar tus cambios, con las mismas comprobaciones que Publicar Formulario. Si alguna comprobación falla, tus cambios se guardan igualmente y la API devuelve 409 Conflict con form_id y saved_as_draft: true.
  • En un formulario que ya está publicado, published: true no cambia nada: llama a Publicar Formulario para publicar tus cambios.
  • published: false despublica un formulario publicado, igual que Despublicar Formulario.

En los formularios de equipo, solo los administradores y propietarios del equipo pueden cambiar published.

Parámetros de Ruta

idstring

El ID del formulario

Cuerpo de Solicitud

Acepta todos los campos de Crear Formulario excepto team_id. Solo incluye los campos que deseas cambiar.

Ejemplo de Solicitud

json
{
  "title": "Updated Survey Title",
  "description": "Revised description for Q2",
  "theme_color": "#10b981",
  "questions": [
    {
      "id": "66a1b2c3d4e5f6a7b8c9d001",
      "type": "short_text",
      "title": "What is your full name?",
      "required": true
    },
    {
      "type": "long_text",
      "title": "Any additional comments?",
      "required": false
    }
  ]
}

Respuesta

Devuelve el objeto del formulario actualizado con todas las preguntas (mismo esquema que Obtener Formulario).

Ejemplos de Código

bash
curl -X PUT "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated Survey Title",
    "theme_color": "#10b981"
  }'

Eliminar Formulario

DELETE/api/v1/forms/:id

Elimina permanentemente un formulario y todos los datos asociados, incluyendo preguntas, respuestas, versiones y entradas de changelog. Las cargas de archivos asociadas se limpian de forma asíncrona.

Esta acción es irreversible. Todas las respuestas recopiladas para este formulario se eliminarán permanentemente.

Parámetros de Ruta

idstring

El ID del formulario

Parámetros de Consulta

delete_signed_contractsboolean

Debe ser true para eliminar un formulario que tiene contratos firmados completados. Se eliminan de forma permanente junto con el formulario, incluidos los PDF firmados y las pistas de auditoría. Sin él, ese formulario no se elimina: la API responde 409 con reason: form_has_signed_contracts y signed_contracts (cuántos hay).

Respuesta

json
{
  "success": true
}

Ejemplos de Código

bash
curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e" \
  -H "Authorization: Bearer YOUR_API_KEY"

Publicar Formulario

POST/api/v1/forms/:id/publish

Publica un formulario creando una instantánea versionada del formulario actual y sus preguntas: el mismo proceso que el botón Publicar del editor. Cada publicación incrementa el número de versión y el formulario se vuelve accesible públicamente en su URL compartible.

Antes de publicar nada, NueForm comprueba que:

  • los formularios de equipo solo los publican los administradores y propietarios del equipo, y los formularios personales solo su propietario (cualquier otra persona recibe 403 Forbidden, o 404 Not Found si no es miembro del equipo del formulario);
  • las funciones Pro (preguntas de reserva, contratos con firma electrónica, nodos de datos, webhooks de formulario y pagos en tu propia cuenta de Stripe) están incluidas en el plan del propietario del formulario (el plan del propietario del equipo en los formularios de equipo);
  • las preguntas de reserva, los pasos de email y las preguntas Fuse y compuestas están completamente configurados.

Si alguna comprobación falla, el formulario no se publica y la API devuelve 409 Conflict con un código reason y los question_ids que hay que corregir (consulta Manejo de errores). Las respuestas correctas incluyen published_version y un array warnings con avisos que no bloquean la publicación.

Parámetros de Ruta

idstring

El ID del formulario

Respuesta

Devuelve el formulario publicado con published_version (el nuevo número de versión) y warnings (avisos que no bloquean la publicación; a menudo vacío):

json
{
  "data": {
    "id": "665a1b2c3d4e5f6a7b8c9d0e",
    "title": "Customer Feedback Survey",
    "slug": "a1b2c3d4e5f6",
    "published": true,
    "has_unpublished_changes": false,
    "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
    "published_version": 3,
    "warnings": [
      {
        "code": "booking_attendee_ask",
        "question_id": "66a1b2c3d4e5f6a7b8c9d004",
        "question_title": "Book a demo",
        "message": "Booking question \"Book a demo\" has no attendee email mapping, so respondents will be asked for their email when they book."
      }
    ],
    "questions": [ ... ]
  }
}

Publicación bloqueada (409)

No se publica nada. reason indica qué comprobación falló y question_ids enumera las preguntas que hay que corregir; upgrade_required es true cuando hay que mejorar el plan del propietario del formulario:

json
{
  "error": {
    "code": "CONFLICT",
    "message": "E-signature contracts need a Pro plan to go live. Upgrade to publish this form, or remove the contract question.",
    "status": 409,
    "reason": "contract_requires_pro",
    "question_ids": ["66a1b2c3d4e5f6a7b8c9d001"],
    "upgrade_required": true
  }
}

Ejemplos de Código

bash
curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Despublicar Formulario

DELETE/api/v1/forms/:id/publish

Despublica un formulario, haciéndolo inaccesible en su URL pública. La instantánea de la versión publicada se conserva para que puedas volver a publicar posteriormente. Los formularios de equipo solo pueden despublicarlos los administradores y propietarios del equipo, y los formularios personales su propietario; cualquier otra persona recibe 403 Forbidden, o 404 Not Found si no es miembro del equipo del formulario.

Parámetros de Ruta

idstring

El ID del formulario

Respuesta

Devuelve el objeto del formulario actualizado con published establecido en false.

json
{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "published": false,
  "questions": [ ... ]
}

Ejemplos de Código

bash
curl -X DELETE "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/publish" \
  -H "Authorization: Bearer YOUR_API_KEY"

Duplicar Formulario

POST/api/v1/forms/:id/duplicate

Crea una copia de un formulario existente, incluyendo todas las preguntas. Las referencias de saltos lógicos se remapean automáticamente a los nuevos IDs de preguntas. El formulario duplicado siempre se crea en estado no publicado.

Parámetros de Ruta

idstring

El ID del formulario a duplicar

Cuerpo de Solicitud

titlestring

Título para el nuevo formulario (por defecto: "Título Original (Copia)")

team_idstring

Asignar el duplicado a un equipo diferente

Ejemplo de Solicitud

json
{
  "title": "Customer Feedback Survey v2",
  "team_id": "665b2c3d4e5f6a7b8c9d0e1f"
}

Respuesta

Devuelve el objeto del formulario recién creado (mismo esquema que Obtener Formulario) con published establecido en false.

Ejemplos de Código

bash
curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/duplicate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Customer Feedback Survey v2" }'

Respuestas de Error

Todos los endpoints devuelven respuestas de error estándar.

Códigos de Error

400Bad Request

Error de validación o campo requerido faltante

401Unauthorized

API key faltante o inválida

403Forbidden

Permisos insuficientes para formularios de equipo

404Not Found

Formulario no encontrado

409Conflict

Publicación bloqueada: falló una comprobación de publicación (consulta Publicar Formulario)

500Server Error

Error interno del servidor

Ejemplo de Error

json
{
  "error": "Title is required"
}
Ultima actualizacion: 8 de octubre de 2026