API

Actualizado 20 de octubre de 2026

En esta página

La API REST de SurveyNinja permite que tus aplicaciones trabajen con encuestas y respuestas: obtener la lista de encuestas, leer respuestas, exportarlas y gestionar variables ocultas y webhooks. La API devuelve JSON.

Este artículo explica lo básico. La referencia completa con todos los endpoints y parámetros está en surveyninja.io/dev/api.

Antes de empezar

Una clave API pertenece a la cuenta del propietario del espacio de trabajo: las solicitudes hechas con la clave tienen el mismo acceso que el propietario. En el espacio de trabajo de otra persona, la sección API / MCP solo se abre si tu rol tiene acceso a ella, y las claves que crees ahí se agregan a la cuenta del propietario.

Crear una clave API

Haz clic en el ícono de tu perfil en la esquina superior derecha y elige API / MCP.
Haz clic en Generar clave API (1).
En la ventana Generar nueva clave API, escribe el Nombre de la clave (al menos 3 caracteres), por ejemplo "CRM sync", y haz clic en Crear clave.
Copia la clave y guárdala en un lugar seguro. Luego haz clic en He guardado la clave, cerrar la ventana.

Importante. La clave se muestra una sola vez. Si la pierdes, elimínala y crea una nueva.

La lista muestra los últimos caracteres de cada clave y cuándo se creó (Creado) y se usó por última vez (Último uso). Para cambiar el nombre de una clave o eliminarla, abre su menú (2) y elige Renombrar o Eliminar. Para eliminarla, confirma en la ventana Eliminar clave API. Para que una aplicación deje de usar la API, elimina su clave: las solicitudes con una clave eliminada reciben el código 401.

Hacer solicitudes

Todas las solicitudes van a esta URL base:

https://api.surveyninja.io/api/v3/service

Pasa la clave en el encabezado Authorization de cada solicitud:

Authorization: Bearer YOUR_API_KEY

Por ejemplo, esta solicitud devuelve la lista de tus encuestas:

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Si falta la clave o es incorrecta, la API responde con el código 401.

Las integraciones creadas con las rutas antiguas de la API (/api/service) también funcionan con las claves nuevas. Para integraciones nuevas, usa la API v3.

Endpoints principales

Las rutas son relativas a la URL base.

Método	Ruta	Qué hace
GET	/user	Información sobre el propietario de la clave
GET	/workspaces	Tus espacios de trabajo
GET	/folders	Carpetas de tu espacio de trabajo
GET	/quiz	Lista de encuestas
GET	/quiz/{id}	Datos y preguntas de la encuesta
POST	/quiz	Crear una encuesta
POST	/quiz/{id}/publish	Publicar una encuesta
GET	/quiz/{id}/answers	Lista de respuestas
GET	/quiz/{id}/answers/csv	Respuestas en un archivo CSV
GET	/quiz/{id}/answers/xlsx	Respuestas en un archivo de Excel
GET	/quiz/{id}/summary	Resumen: visitas, respuestas completas, tasa de finalización
GET	/quiz/{id}/hidden/variables	Variables ocultas de una encuesta
GET	/quiz/{id}/webhooks	Webhooks de una encuesta

La API también cubre los ajustes de la encuesta, temas, carpetas, participantes, códigos promocionales, enlaces únicos e informes. Consulta la lista completa en la referencia de la API.

Obtener la lista de encuestas

GET /quiz acepta estos parámetros de consulta:

Parámetro	Descripción
limit, offset	Paginación
sort	created_at, updated_at, name o id. Predeterminado: id
order	desc o asc. Predeterminado: desc
folder_id	Devuelve solo las encuestas de una carpeta

La respuesta es un arreglo con las encuestas del espacio de trabajo del propietario de la clave. Sin limit, incluye todas. Cada encuesta tiene id, name, type, url_shared (el enlace público), is_published, created_at, updated_at, folder y notes.

Obtener respuestas

GET /quiz/{id}/answers devuelve las respuestas de una encuesta, de forma predeterminada las más recientes primero.

Parámetro	Descripción
limit	Número de respuestas, hasta 100. Predeterminado: 20
offset	Cuántas respuestas omitir. Predeterminado: 0
date	Respuestas de un día, en formato YYYY-MM-DD
is_complete	true para solo respuestas completas, false para las incompletas
sort	date_start o date_end
order	desc o asc

Ejemplo de solicitud:

curl -X GET "https://api.surveyninja.io/api/v3/service/quiz/123/answers?limit=50&amp;is_complete=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Ejemplo de respuesta (abreviado):

{
  "answers": [
    {
      "id": 4813,
      "visit_id": 46139,
      "date": "2026-08-24T12:51:33",
      "date_start": "2026-08-24T12:50:52",
      "date_end": "2026-08-24T12:51:33",
      "filling_time_seconds": 41,
      "extra_fields": { "utm_source": "newsletter" },
      "is_complete": true,
      "is_respondent": false,
      "answers": [
        {
          "type": "input",
          "rowId": "87a748c3-43e5-4ecc-bba2-413deb908864",
          "title": "¿Qué deberíamos mejorar?",
          "result": "Un soporte más rápido",
          "min_val": null,
          "max_val": null,
          "hidden_options": null
        },
        {
          "type": "userInfo",
          "title": "User info",
          "result": {
            "ip": "203.0.113.10",
            "browser": "Chrome",
            "country": "Germany",
            "user_agent": "Mozilla/5.0 ...",
            "password_number": null,
            "import_source": null,
            "is_anonymous": false
          },
          "is_anonymous": false
        }
      ],
      "over_upload_limit": false,
      "unique_link": null
    }
  ],
  "answer_total_count": 128
}

En cada respuesta, answers contiene un objeto por pregunta. rowId es el ID de la pregunta y result es la respuesta. El último objeto, de tipo userInfo, contiene los datos técnicos del encuestado. En las encuestas anónimas, la dirección IP, el navegador, el país y el user agent son null. Si ninguna respuesta coincide con la solicitud, answers es null.

answer_total_count es el número total de respuestas de la encuesta, incluidas las incompletas y las descalificadas. Los filtros date e is_complete no lo cambian, así que no lo uses para contar las páginas de una solicitud filtrada.

MCP para asistentes de IA

La misma clave API conecta SurveyNinja con asistentes de IA compatibles con Model Context Protocol (MCP), como Claude o Cursor. MCP está disponible en todos los planes, incluido el Gratuito. Cómo configurarlo se explica en Conectar asistentes de IA (MCP).

Límites

Una cuenta puede tener hasta 5 claves API.
GET /quiz/{id}/answers devuelve hasta 100 respuestas por solicitud. Para obtener el resto, usa limit y offset.
GET /quiz/{id}/answers no devuelve las respuestas descalificadas ni las eliminadas.
El nombre de una clave debe tener al menos 3 caracteres.

Si algo no funciona

La API responde con el código 401. Falta la clave, está mal escrita o se eliminó. Revisa el encabezado: la palabra Bearer, un espacio y la clave.
"Ha superado el límite para crear claves API" al hacer clic en Generar clave API. La cuenta ya tiene 5 claves. Pasar a un plan superior no aumenta este límite. Elimina una clave que ya no uses.
La API devuelve solo 20 respuestas. Es el límite predeterminado. Pasa limit (hasta 100) y offset para obtener más.

API