> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# API de cuestionarios KYC: formularios dinámicos

> Los cuestionarios de Didit crean formularios KYC personalizados arrastrando y soltando, con idiomas, lógica condicional y revisión manual. $0.10 por llamada.

Los cuestionarios de Didit te permiten diseñar formularios dinámicos y estructurados para recopilar información adicional de los usuarios durante la verificación. Usa nuestro editor visual para arrastrar y soltar elementos, organizar el contenido en secciones, localizar los textos en varios idiomas y derivar los resultados a revisión manual cuando haga falta.

Prompt de integración de cuestionarios
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Questionnaires (custom KYC/KYB forms with conditional logic and manual-review routing) into your app.

\# Delivery mode
Questionnaires are **session-only**. The form is designed in the Business Console (drag-and-drop builder) and bound to a workflow via the QUESTIONNAIRE feature. There is no standalone questionnaire submission API — answers are collected through the hosted Didit flow.

\# Steps
1\. Build the questionnaire in the Business Console (Questionnaires tab). Define sections, fields, conditional visibility, multi-language labels, and **custom status rules** (e.g. "if source_of_funds = 'crypto' set status to In Review").
2\. Add the QUESTIONNAIRE feature to a workflow and select the questionnaire id (POST /v3/workflows/ or the Console).
3\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
4\. Open session.url for the user (or mount the Web/Mobile SDK) — the form renders inside the flow.
5\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-1234",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `questionnaire_responses[]` on the decision payload (one entry per questionnaire node). Each entry includes:
\- `status` — final status for this questionnaire instance (driven by your custom status rules).
\- `answers` — array of { question_id, question_label, value } pairs (or nested sections).
\- `warnings` — any rule-triggered warnings.

\# Status enum (per questionnaire_responses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.QUESTIONNAIRE)
The dominant risk code is CUSTOM_STATUS_RULE_TRIGGERED — emitted whenever an answer matches a Console-configured rule that escalates the status. The warning's `additional_data` carries the rule id and matched answer so reviewers can see why the session was routed.

Full catalogue: questionnaire warnings are documented inside the report page — see /core-technology/questionnaires/report-questionnaire.

\# Failure modes to handle
\- questionnaire_responses[] empty — user abandoned the form. The session status will reflect "Abandoned"; treat per your retention policy.
\- status="In Review" with CUSTOM_STATUS_RULE_TRIGGERED — answers crossed your manual-review rule; surface the relevant answers in your reviewer UI.
\- status="Declined" — answers crossed a decline rule (e.g. user declared they are a sanctioned-country resident); do not approve.

\# See also
\- Canonical schema: /reference/data-models#questionnaire-response
\- Per-feature report: /core-technology/questionnaires/report-questionnaire
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

En la lección de Academy sobre cómo leer el resultado de una verificación, el capítulo del minuto 11:54 trata sobre Document AI y los cuestionarios.[Document AI y cuestionarios — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## Dos formas de crear cuestionariosDidit ofrece **dos enfoques distintos** para crear cuestionarios, para que elijas el nivel de complejidad que necesitas:![Modos simple y avanzado del constructor de cuestionarios KYC de Didit, uno junto al otro](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple-and-complex.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=71d18d67b4684cca46c7809ba43cfcb6)### 1. Modo simple: constructor rápido de formulariosEl **modo simple** es ideal para crear formularios sencillos con rapidez. Usa nuestra interfaz intuitiva de arrastrar y soltar para añadir elementos, marcar campos como obligatorios y publicar en minutos.![Interfaz del constructor de formularios de arrastrar y soltar en modo simple de los cuestionarios de Didit](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-simple.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=8e777d8fc72ca16e8e2deb65a0a66e92)**Ideal para:**- Formularios de recopilación rápida de datos
- Encuestas y declaraciones sencillas
- Equipos que empiezan con los constructores de formularios
- Cuestionarios en un solo idioma**Cómo funciona:**1) Abre el constructor de cuestionarios
2) Arrastra elementos de la paleta a tu formulario
3) Configura cada elemento (etiqueta, obligatorio, marcador de posición)
4) Previsualiza y publica***### 2. Modo avanzado: constructor visual de grafosEl **modo avanzado** desbloquea funciones potentes para escenarios complejos de recopilación de datos mediante un **editor visual basado en nodos**. Crea cuestionarios sofisticados con lógica condicional, rutas ramificadas y control total del flujo.![Editor visual de grafos basado en nodos del cuestionario avanzado de Didit, con lógica de ramificación](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-node-based.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=7ff0c1d79f500ed3f78dca4ff89b0698)**Ideal para:**- Cuestionarios multilingües
- Formularios complejos con ramificación condicional
- Recopilación de datos orientada al cumplimiento con distintas rutas
- Formularios que requieren flujos de revisión manual**Capacidades clave:**- **Editor visual de nodos**: arrastra, suelta y conecta nodos en un lienzo infinito
- **Conexiones inteligentes**: arrastra desde el asa de un nodo hasta un espacio vacío para crear y conectar un nodo nuevo al instante
- **Ramificación condicional**: dirige a los usuarios a preguntas distintas según sus respuestas anteriores y luego [reúne las rutas en un paso compartido](#reunir-las-rutas-de-una-rama-en-un-paso-compartido)
- **Compatibilidad con varios idiomas**: traduce todo el contenido visible para el usuario
- **Atajos de teclado**: deshacer (Ctrl/Cmd+Z), rehacer (Ctrl/Cmd+Shift+Z), eliminar (Supr/Retroceso)
- **Zoom y desplazamiento**: navega por formularios complejos con zoom con la rueda y desplazamiento arrastrando#### Tipos de nodo del constructor de grafos| Tipo de nodo | Color | Descripción | Cuándo usarlo |
| - | - | - | - |
| **Nodos de pregunta** | Azul | Elementos de entrada que recogen datos del usuario | Campos de texto, listas desplegables, subida de archivos, fechas, etc. |
| **Nodos de texto** | Verde | Contenido de solo lectura mostrado a los usuarios | Instrucciones, explicaciones, textos legales |
| **Nodos de rama** | Naranja | Enrutamiento condicional según las respuestas | «Si el país es EE. UU., mostrar el formulario fiscal» |
| **Nodos de sección** | Gris | Agrupación visual de elementos relacionados | Organizar las preguntas en secciones lógicas |> **Reglas de conexión:** los nodos de sección y de texto pueden conectarse a nodos de pregunta y a otros nodos de texto, pero no directamente a nodos de rama. Los nodos de rama pueden conectarse a cualquier tipo de nodo.#### Reunir las rutas de una rama en un paso compartidoLa ramificación no tiene por qué ser de un solo sentido. El final de varias rutas puede conectarse al mismo nodo posterior, y el cuestionario continúa desde ahí una sola vez. Las preguntas compartidas se crean y se mantienen en un solo lugar en lugar de repetirse al final de cada ruta.**Ejemplo práctico: preguntas adicionales en caso de Sí y un tramo final compartido**1) Añade un nodo **Pregunta** con una pregunta de **Opción única** que ofrezca Sí y No, y después un nodo **Rama** con una ruta `Yes` y una ruta `No`.
2) En la ruta `Yes`, añade las preguntas adicionales que solo se aplican cuando la respuesta es Sí.
3) Al final de esa ruta, añade la primera pregunta que debe responder todo el mundo después de la rama: el inicio del tramo final compartido.
4) Apunta la ruta `No` a esa pregunta: abre el menú **+** al final de la ruta `No` y elige **Conectar un paso existente**, o arrastra desde el conector de la ruta `No` y suelta sobre el borde superior de la pregunta compartida. El lienzo solo se conecta al pequeño punto de destino de la parte superior de la tarjeta, así que soltar sobre el centro de la tarjeta no hace nada.
5) Sigue añadiendo el resto de las preguntas compartidas tras la primera y publica. El lienzo dibuja el tramo compartido una sola vez, debajo de las rutas que llevan a él.Una ruta puede unirse así a un nodo que ya existe, y varias rutas pueden apuntar al mismo nodo. Unirla define dónde continúa esa ruta, por lo que el menú **+** ofrece **Conectar un paso existente** mientras la ruta termina ahí. Se rechaza una conexión que cierre un bucle hacia un nodo anterior.Los encuestados responden las preguntas compartidas una sola vez, en la ruta que hayan seguido; las preguntas de la ruta que no han seguido se omiten. La carga de la decisión sigue la misma regla: `questionnaire_responses[].sections[].items` lista solo los elementos de la ruta que siguió el encuestado. Consulta [Visibilidad condicional](https://docs.didit.me/core-technology/questionnaires/report-questionnaire.md#conditional-visibility).***## Plantillas de cuestionariosLas plantillas te ayudan a empezar rápido con formularios preconfigurados para casos de uso habituales. Puedes usarlas tal cual o personalizarlas a tu medida.![Plantillas predefinidas de cuestionarios de Didit para origen de fondos y cumplimiento KYC](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaires-template.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=97a45bd55692379ffc057e11f4530a54)### Plantillas predefinidas| Plantilla | Descripción | Elementos habituales |
| - | - | - |
| **Origen de fondos** | Recoge las fuentes de ingresos y la documentación de respaldo | Lista desplegable, texto largo, subida de archivos |
| **Datos laborales** | Recoge el puesto, el empleador y el rango de ingresos | Texto corto, lista desplegable, número |
| **Finalidad de la cuenta** | Entiende el uso previsto de la cuenta | Opción única, opción múltiple, texto largo |
| **Titularidad real** | Identifica a los UBO y la estructura de propiedad | Texto corto, número, subida de archivos |
| **Residencia fiscal** | Recoge las declaraciones de carácter fiscal | País, consentimiento, subida de archivos |
| **Evaluación de riesgos** | Reúne información relevante para el riesgo | Opción múltiple, lista desplegable, texto largo |***## Cómo funcionaNuestro flujo de cuestionarios está diseñado para ser flexible y auditable:### 1. Créalo en la consola (sin código)- Arrastra y suelta elementos para crear tu cuestionario
- Organiza el contenido en varias secciones para mayor claridad
- Marca los elementos como obligatorios u opcionales
- Configura marcadores de posición y descripciones de ayuda
- Añade opciones (con seguimiento opcional en texto libre) para las listas desplegables y la opción única
- Configura los límites de subida de archivos e imágenes por elemento### 2. Localiza el contenido- Escribe tu contenido una sola vez en el `default_language` del cuestionario
- Define los `languages` compatibles: al publicar, cada título, descripción, marcador de posición, etiqueta de opción y mensaje de validación se **traduce automáticamente** a todos ellos
- Ajusta cualquier traducción a mano en el constructor; las ediciones manuales se conservan hasta que cambia el texto original
- El usuario final ve el contenido automáticamente en el mejor idioma disponible### 3. Publica y recopila- Activa el cuestionario e insértalo en tu flujo de verificación
- Los usuarios finales completan las secciones y envían sus respuestas
- Los archivos subidos (documentos, imágenes) se almacenan y se vinculan a la respuesta### 4. Revisa y decide* Las respuestas se guardan con un `status`: `Approved`, `In Review` o `Not Finished`
* Puedes forzar que todas las respuestas del cuestionario pasen a `In Review`, para que una persona las apruebe manualmente
* Revisa las respuestas y los archivos en la consola y márcalos como `Approved`> Nota: los cuestionarios no generan advertencias de riesgo. La gobernanza se consigue con campos obligatorios, validación y flujos de revisión.***## Capacidades clave| Capacidad | Modo simple | Modo avanzado |
| - | - | - |
| Constructor de arrastrar y soltar | ✅ | ✅ |
| Campos obligatorios y opcionales | ✅ | ✅ |
| Marcadores de posición y descripciones | ✅ | ✅ |
| Varias secciones | ✅ | ✅ |
| Límites de subida de archivos | ✅ | ✅ |
| Editor visual de grafos | ❌ | ✅ |
| Ramificación condicional | ❌ | ✅ |
| Traducciones a varios idiomas | ❌ | ✅ |
| Lógica de opciones (exigir texto) | ❌ | ✅ |
| Forzar revisión manual | ❌ | ✅ |
| Compatibilidad con deshacer y rehacer | ❌ | ✅ |
| Atajos de teclado | ❌ | ✅ |**Lista completa de funciones:**- **Constructor visual**: crea y gestiona cuestionarios con un editor intuitivo de arrastrar y soltar
- **Secciones**: agrupa preguntas relacionadas; añade encabezados y separadores para guiar a los usuarios
- **Traducciones automáticas**: escribe el contenido en un idioma y todo el texto visible para el usuario se traduce a los demás idiomas seleccionados al publicar, con posibilidad de ajuste manual
- **Validación**: marca los campos como obligatorios; aplica un máximo de archivos por elemento de subida
- **Lógica de opciones**: en listas desplegables y opción única, puedes exigir texto adicional por cada opción seleccionada
- **Subidas**: recopila documentos e imágenes con límites en el número de archivos (por ejemplo, hasta 3 archivos)
- **Revisión manual**: opcionalmente fuerza que todas las respuestas pasen a `In Review` a la espera de la aprobación de una persona
- **Interruptor de activación**: activa o desactiva el cuestionario por aplicación
- **Integración con flujos de verificación**: añade cuestionarios a KYC o ejecútalos por separado como un flujo de verificación de cuestionario
- **APIs y webhooks**: lee los resultados estructurados por API y recibe actualizaciones***## Tipos de elementoPuedes añadir los siguientes tipos de elemento en el constructor (seleccionables desde la consola):### Elementos de entrada| Elemento | Descripción | Opciones de configuración |
| - | - | - |
| **SHORT\_TEXT** | Texto libre de una línea | Marcador de posición, obligatorio |
| **LONG\_TEXT** | Texto libre de varias líneas | Marcador de posición, obligatorio |
| **NUMBER** | Entrada numérica | Marcador de posición, obligatorio |
| **EMAIL** | Entrada de correo electrónico con validación | Marcador de posición, obligatorio |
| **PHONE** | Entrada de número de teléfono | Marcador de posición, obligatorio |
| **ADDRESS** | Entrada de dirección | Marcador de posición, obligatorio |
| **DATE\_PICKER** | Selección de fecha | Marcador de posición, obligatorio |
| **TIME** | Entrada de hora | Marcador de posición, obligatorio |### Elementos de opción| Elemento | Descripción | Opciones de configuración |
| - | - | - |
| **DROPDOWN** | Selección única de una lista | Opciones, `requires_text_input` por opción |
| **SINGLE\_CHOICE** | Selección única tipo radio | Opciones, `requires_text_input` por opción |
| **MULTIPLE\_CHOICE** | Lista de selección múltiple | Opciones |
| **COUNTRY** | Selector de país | Obligatorio |
| **CONSENT** | Casilla o acuse de recibo | Obligatorio, etiqueta personalizada |### Elementos de subida| Elemento | Descripción | Opciones de configuración |
| - | - | - |
| **IMAGE** | Subida de imagen | `max_files` (1-5), obligatorio |
| **FILE\_UPLOAD** | Subida de documento | `max_files` (1-5), obligatorio |### Elementos de diseño| Elemento | Descripción | Notas |
| - | - | - |
| **PARAGRAPH** | Texto explicativo de solo lectura | No admite respuesta |
| **SECTION\_HEADER** | Encabezado visual de sección | No admite respuesta, no es obligatorio |
| **SEPARATOR** | Divisor visual | No admite respuesta, no es obligatorio |**Notas de comportamiento:**- `SECTION_HEADER` y `SEPARATOR` son solo de presentación. Ignoran obligatorio, marcador de posición, opciones y límites de archivos.
- En los elementos de opción, define las opciones como `{ label, value, requires_text_input? }`.
- En los elementos de subida, define `max_files` (1–5) para controlar cuántos archivos se pueden adjuntar.***## Forzar la revisión manualAlgunos flujos de cumplimiento exigen la revisión humana de cada respuesta. Desde la consola puedes configurar los cuestionarios para que siempre den como resultado `In Review`. Después, un revisor aprueba o solicita cambios, y a continuación la respuesta pasa a `Approved`.**Cuándo usar la revisión manual:**- Alta de clientes de alto riesgo
- Recopilación de datos sensibles (origen de fondos, declaraciones de UBO)
- Requisitos normativos de supervisión humana
- Control de calidad durante el despliegue inicial***## Ejemplos de casos de uso### Origen de fondosRecoge las fuentes de ingresos, los importes y los documentos de respaldo subidos (por ejemplo, nóminas, extractos). Combina listas desplegables, texto largo y subida de archivos.**Estructura típica:**- Sección 1: situación laboral (lista desplegable)
- Sección 2: fuentes de ingresos (opción múltiple + texto largo)
- Sección 3: documentos de respaldo (subida de archivos)
- Sección 4: declaración (consentimiento)***### Asociación o afiliaciónRegistra afiliaciones, cargos y pruebas de pertenencia; incluye elementos de consentimiento para las declaraciones.**Estructura típica:**- Nombre de la organización (texto corto)
- Cargo o puesto (lista desplegable)
- Duración de la afiliación (selector de fecha)
- Prueba de afiliación (subida de archivos)
- Declaración (consentimiento)***### Finalidad de la relación y actividad prevista de la cuentaRecoge la intención, los volúmenes de transacciones previstos, los países de actividad y las contrapartes previstas. Usa opción única o múltiple, campos numéricos y párrafos de contexto.**Estructura típica:**- Sección 1: finalidad de la cuenta (opción múltiple)
- Sección 2: volumen mensual previsto (número + lista desplegable para la divisa)
- Sección 3: países de actividad (país - múltiple)
- Sección 4: tipos de transacción (opción múltiple)
- Sección 5: información adicional (texto largo)***## Modo simple o avanzado: cuándo usar cada uno| Escenario | Modo recomendado |
| - | - |
| Formulario básico en un solo idioma | Simple |
| Se necesita compatibilidad con varios idiomas | Avanzado |
| Encuesta interna rápida | Simple |
| Cuestionario de cumplimiento | Avanzado |
| Recopilación de datos puntual | Simple |
| Rutas de ramificación condicional | Avanzado |
| Forzar revisión manual | Avanzado |
| Formularios complejos con varias secciones | Avanzado |***## Primeros pasos1. **¿Primera vez con los cuestionarios?** Empieza con el **modo simple** para aprender el constructor
2. **¿Necesitas traducciones o lógica condicional?** Pasa al **modo avanzado** para usar el editor visual de grafos> Consulta cómo se estructuran los resultados en la página del [informe de cuestionarios](https://docs.didit.me/core-technology/questionnaires/report-questionnaire.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.