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

Si el formulario está publicado (por defecto: false)

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)

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,
  "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.

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

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"

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

Parámetros de Ruta

idstring

El ID del formulario

Respuesta

Devuelve el objeto del formulario con un campo published_version indicando el nuevo número de versión:

json

{
  "id": "665a1b2c3d4e5f6a7b8c9d0e",
  "title": "Customer Feedback Survey",
  "slug": "a1b2c3d4e5f6",
  "published": true,
  "has_unpublished_changes": false,
  "published_version_id": "66c3d4e5f6a7b8c9d0e1f2a3",
  "published_version": 3,
  "questions": [ ... ]
}

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.

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

500Server Error

Error interno del servidor

Ejemplo de Error

json

{
  "error": "Title is required"
}

Ultima actualizacion: 6 de abril de 2026