API de Respuestas

Obtén, filtra, elimina y exporta las respuestas de formularios.

La API de Respuestas te permite obtener, filtrar, eliminar y exportar los envíos recopilados por tus formularios. Todas las respuestas están asociadas a un formulario específico.

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

Endpoints

GET/api/v1/forms/:id/responsesGET/api/v1/forms/:id/responses/:responseIdDELETE/api/v1/forms/:id/responses/:responseIdPOST/api/v1/forms/:id/responses/bulk-deleteGET/api/v1/forms/:id/responses/export

Listar Respuestas

GET/api/v1/forms/:id/responses

Devuelve una lista paginada de respuestas de un formulario, ordenadas por fecha de envío (más recientes primero).

Parámetros de Ruta

idstringobligatorio

El ID del formulario

Parámetros de Consulta

pageinteger

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

per_pageinteger

Resultados por página (por defecto: 50)

sincestring

Fecha ISO 8601. Solo devolver respuestas enviadas en o después de esta fecha.

untilstring

Fecha ISO 8601. Solo devolver respuestas enviadas en o antes de esta fecha.

completedboolean

Filtrar por estado de completitud. true devuelve solo respuestas completadas, false devuelve solo respuestas parciales.

Tipos de Valor de Respuesta

short_textstring

Ejemplo: "Jane Smith"

long_textstring

Ejemplo: "I really enjoyed the product..."

multiple_choicestring

Ejemplo: "Option A"

multiple_choice (multi)array of strings

Ejemplo: ["Option A", "Option C"]

ratingnumber

Ejemplo: 4

opinion_scalenumber

Ejemplo: 8

numbernumber

Ejemplo: 42

emailstring

Ejemplo: "jane@example.com"

datestring (ISO 8601)

Ejemplo: "2026-03-15"

yes_noboolean

Ejemplo: true

file_uploadobject

Ejemplo: { "url": "...", "name": "doc.pdf" }

dropdownstring

Ejemplo: "United States"

Respuesta

json

{
  "responses": [
    {
      "id": "667a1b2c3d4e5f6a7b8c9d01",
      "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
      "visitor_id": "v_8f2k3j4l5m6n",
      "submitted_at": "2026-02-27T15:42:00.000Z",
      "completed_at": "2026-02-27T15:45:30.000Z",
      "metadata": {
        "user_agent": "Mozilla/5.0",
        "referrer": "https://example.com"
      },
      "answers": [
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d001",
          "value": "Jane Smith"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d002",
          "value": "Social media"
        },
        {
          "question_id": "66a1b2c3d4e5f6a7b8c9d003",
          "value": 5
        }
      ],
      "quiz_results": null
    }
  ],
  "total": 142,
  "page": 1,
  "per_page": 50
}

Ejemplos de Código

bash

curl -X GET "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses?page=1&per_page=25&completed=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obtener Respuesta

GET/api/v1/forms/:id/responses/:responseId

Obtiene una respuesta individual por ID.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

responseIdstringobligatorio

El ID de la respuesta

Resultados de Quiz

Para formularios que usan modos de quiz (knowledge_quiz, lead_qualification, match_quiz), el campo quiz_results contiene datos de puntuación.

Respuesta

json

{
  "id": "667a1b2c3d4e5f6a7b8c9d01",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "visitor_id": "v_8f2k3j4l5m6n",
  "submitted_at": "2026-02-27T15:42:00.000Z",
  "completed_at": "2026-02-27T15:45:30.000Z",
  "metadata": {
    "user_agent": "Mozilla/5.0",
    "referrer": "https://example.com"
  },
  "answers": [
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d001",
      "value": "Jane Smith"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d002",
      "value": "Social media"
    },
    {
      "question_id": "66a1b2c3d4e5f6a7b8c9d003",
      "value": 5
    }
  ],
  "quiz_results": null
}

Ejemplo de Resultados de Quiz

json

{
  "quiz_results": {
    "score": 8,
    "correct_answers": 4,
    "total_scorable_questions": 5,
    "max_score": 10,
    "matched_ending_id": null,
    "form_mode": "knowledge_quiz"
  }
}

Ejemplos de Código

bash

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

Eliminar Respuesta

DELETE/api/v1/forms/:id/responses/:responseId

Elimina permanentemente una respuesta individual.

Esta acción es irreversible. Los datos de la respuesta no se pueden recuperar después de la eliminación.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

responseIdstringobligatorio

El ID de la respuesta

Respuesta

json

{
  "success": true
}

Ejemplos de Código

bash

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

Eliminación Masiva de Respuestas

POST/api/v1/forms/:id/responses/bulk-delete

Elimina múltiples respuestas en una sola solicitud. Máximo de 100 respuestas por solicitud. Todos los IDs de respuesta especificados deben pertenecer al formulario indicado.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

Cuerpo de Solicitud

response_idsarray of stringsobligatorio

IDs de las respuestas a eliminar (máx. 100)

Ejemplo de Solicitud

json

{
  "response_ids": [
    "667a1b2c3d4e5f6a7b8c9d01",
    "667a1b2c3d4e5f6a7b8c9d02",
    "667a1b2c3d4e5f6a7b8c9d03"
  ]
}

Respuesta

json

{
  "deleted": 3
}

Ejemplos de Código

bash

curl -X POST "https://api.nueform.io/api/v1/forms/665a1b2c3d4e5f6a7b8c9d0e/responses/bulk-delete" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "response_ids": [
      "667a1b2c3d4e5f6a7b8c9d01",
      "667a1b2c3d4e5f6a7b8c9d02"
    ]
  }'

Exporta todas las respuestas de un formulario como archivo CSV. El CSV incluye columnas para responseId, submittedAt, completedAt y una columna por pregunta (usando el título de la pregunta como encabezado de columna).

Para preguntas de grupo (question_group, multi_question_page, contact_info, address), cada subcampo obtiene su propia columna.

Parámetros de Ruta

idstringobligatorio

El ID del formulario

Respuesta

Devuelve un archivo CSV con Content-Type: text/csv.

text

responseId,submittedAt,completedAt,What is your name?,How did you hear about us?,How would you rate your overall experience?
667a1b2c3d4e5f6a7b8c9d01,2026-02-27T15:42:00.000Z,2026-02-27T15:45:30.000Z,Jane Smith,Social media,5
667a1b2c3d4e5f6a7b8c9d02,2026-02-26T10:15:00.000Z,2026-02-26T10:18:22.000Z,Bob Johnson,Search engine,4
667a1b2c3d4e5f6a7b8c9d03,2026-02-25T08:30:00.000Z,,Alex Chen,Friend or colleague,

Ejemplos de Código

bash

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

Respuestas de Error

Todos los endpoints devuelven respuestas de error estándar:

Códigos de Estado

400Bad Request

Parámetros inválidos, eliminación masiva excede 100 elementos

401Unauthorized

API key faltante o inválida

403Forbidden

Permisos de equipo insuficientes

404Not Found

Formulario o respuesta no encontrados

500Internal Server Error

Error interno del servidor

Ejemplo de Error

json

{
  "error": "Response not found"
}

Ultima actualizacion: 6 de abril de 2026