> ## 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 qüestionaris KYC: formularis dinàmics

> Crea qüestionaris KYC personalitzats amb Didit: lògica condicional, multiidioma i enviament a revisió manual. Pagament per crida a $0.10.

Els Qüestionaris de Didit et permeten dissenyar formularis estructurats i dinàmics per recopilar informació addicional dels usuaris durant la verificació. Utilitza el nostre creador visual per arrossegar i deixar anar elements, organitzar el contingut en seccions, localitzar el text en diversos idiomes i encaminar els resultats a revisió manual quan calgui.

Prompt d'integració de Qüestionaris
        Copia el prompt al porta-retalls



      
      

\<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>



      
      

Enganxa a

A la lliçó de l'Academy sobre com interpretar el resultat d'una verificació, el capítol del minut 11:54 tracta sobre Document AI i els qüestionaris.[Document AI i qüestionaris — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## Dues maneres de crear qüestionarisDidit ofereix **dos enfocaments diferents** per crear qüestionaris, cosa que et permet triar el nivell de complexitat adequat per a les teves necessitats:![Modes simple i avançat del creador de qüestionaris KYC de Didit, l'un al costat de l'altre](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. Mode simple: Creador ràpid de formularisEl **Mode simple** és perfecte per crear formularis senzills ràpidament. Utilitza la nostra interfície intuïtiva d'arrossegar i deixar anar per afegir elements, definir camps obligatoris i publicar en qüestió de minuts.![Interfície del creador de formularis d'arrossegar i deixar anar del mode simple de qüestionaris 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 per a:**- Formularis ràpids de recollida de dades
- Enquestes i atestacions senzilles
- Equips que comencen a crear formularis
- Qüestionaris en un sol idioma**Com funciona:**1) Obre el Creador de qüestionaris
2) Arrossega elements des de la paleta cap al formulari
3) Configura cada element (etiqueta, obligatori, text de marcador de posició)
4) Previsualitza i publica***### 2. Mode avançat: Creador visual de grafsEl **Mode avançat** desbloqueja funcionalitats potents per a escenaris complexos de recollida de dades mitjançant un **editor visual basat en nodes**. Construeix qüestionaris sofisticats amb lògica condicional, camins de ramificació i control total sobre el flux.![Editor visual de grafs basat en nodes, amb lògica de ramificació, per a qüestionaris avançats de Didit](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 per a:**- Qüestionaris en múltiples idiomes
- Formularis complexos amb ramificació condicional
- Recollida de dades orientada al compliment amb diferents camins
- Formularis que requereixen fluxos de treball de revisió manual**Capacitats clau:**- **Editor visual de nodes**: arrossega, deixa anar i connecta nodes en un llenç infinit
- **Connexions intel·ligents**: arrossega des de la nansa d'un node cap a un espai buit per crear i connectar a l'instant un node nou
- **Ramificació condicional**: dirigeix els usuaris cap a preguntes diferents segons les respostes anteriors, i després [reunifica els camins en un pas compartit](#reunificació-de-branques-en-un-pas-compartit)
- **Compatibilitat amb múltiples idiomes**: tradueix tot el contingut adreçat a l'usuari
- **Dreceres de teclat**: Desfer (Ctrl/Cmd+Z), Refer (Ctrl/Cmd+Shift+Z), Suprimir (Supr/Retrocés)
- **Zoom i desplaçament**: navega per formularis complexos amb desplaçament per fer zoom i arrossegar per desplaçar-se#### Tipus de nodes del creador de grafs| Tipus de node | Color | Descripció | Quan s'ha d'utilitzar |
| - | - | - | - |
| **Nodes de pregunta** | Blau | Elements d'entrada que recopilen dades de l'usuari | Camps de text, desplegables, càrrega de fitxers, dates, etc. |
| **Nodes de text** | Verd | Contingut només de lectura que es mostra als usuaris | Instruccions, explicacions, textos legals |
| **Nodes de ramificació** | Taronja | Encaminament condicional basat en respostes | "Si el país és els EUA, mostra el formulari fiscal" |
| **Nodes de secció** | Gris | Agrupació visual d'elements relacionats | Organitza les preguntes en seccions lògiques |> **Regles de connexió:** els nodes de secció i de text es poden connectar a nodes de pregunta i a altres nodes de text, però no directament a nodes de ramificació. Els nodes de ramificació es poden connectar a qualsevol tipus de node.#### Operadors de condicióUna condició de ramificació compara una resposta anterior amb un valor.
Combina diverses condicions amb `and` o `or`.| Operador | Coincideix quan la resposta |
| - | - |
| `equals` | És igual al valor |
| `not_equals` | No és igual al valor |
| `contains` | Conté el valor |
| `greater_than` | És superior al valor |
| `greater_than_or_equals` | És superior o igual al valor |
| `less_than` | És inferior al valor |
| `less_than_or_equals` | És inferior o igual al valor |
| `in` | És un dels valors d'una llista |
| `not_in` | No és cap dels valors d'una llista |
| `is_empty` | S'ha deixat buida |
| `is_not_empty` | S'ha emplenat |#### Reunificació de branques en un pas compartitLa ramificació no ha de ser necessàriament unidireccional. El final de diversos camins es pot connectar al mateix node posterior, i el qüestionari continua des d'allà una sola vegada. Les preguntes compartides es construeixen i es mantenen en un sol lloc en comptes de repetir-se al final de cada camí.**Exemple pràctic: preguntes addicionals si la resposta és Sí, i després un tram final compartit**1) Afegeix un **node de pregunta** amb una pregunta d'**Opció única** que ofereixi Sí i No, i després un **node de ramificació** a continuació amb un camí `Yes` i un camí `No`.
2) Al camí `Yes`, afegeix les preguntes addicionals que només s'apliquen quan la resposta és Sí.
3) Al final d'aquest camí, afegeix la primera pregunta que tothom ha de respondre després de la branca: l'inici del tram final compartit.
4) Apunta el camí `No` cap a aquesta pregunta: obre el menú **+** al final del camí `No` i tria **Connecta un pas existent**, o arrossega des del connector del camí `No` i deixa'l anar a la vora superior de la pregunta compartida. El llenç només es connecta a l'objectiu petit de la part superior de la targeta, de manera que deixar-lo anar sobre el mig de la targeta no fa res.
5) Continua afegint la resta de preguntes compartides després de la primera i, a continuació, publica. El llenç dibuixa el tram final compartit una sola vegada, a sota dels camins que hi condueixen.Un camí es pot unir a un node que ja existeix d'aquesta manera, i diversos camins poden apuntar cap al mateix node. Enllaçar defineix on continua aquest camí, de manera que el menú **+** ofereix **Connecta un pas existent** mentre el camí acabi allà. Es rebutja qualsevol connexió que tanqui un bucle cap a un node anterior.Els enquestats responen a les preguntes compartides una sola vegada, pel camí que hagin seguit; les preguntes del camí que no han seguit s'ometen. El payload de decisió segueix la mateixa regla: `questionnaire_responses[].sections[].items` només llista els elements del camí que l'enquestat ha seguit. Consulta [Visibilitat condicional](https://docs.didit.me/ca/core-technology/questionnaires/report-questionnaire.md#visibilitat-condicional).***## Plantilles de qüestionarisLes plantilles t'ajuden a començar ràpidament amb formularis preconfigurats per a casos d'ús habituals. Pots utilitzar-les tal com venen o personalitzar-les per adaptar-les a les teves necessitats.![Plantilles predefinides de qüestionaris de Didit per a l'origen dels fons i el compliment de 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)### Plantilles predefinides| Plantilla | Descripció | Elements típics |
| - | - | - |
| **Origen dels fons** | Captura les fonts d'ingressos i la documentació justificativa | Menú desplegable, Text llarg, Pujada de fitxers |
| **Detalls laborals** | Recopila el càrrec, l'empresa ocupadora i el rang d'ingressos | Text curt, Menú desplegable, Número |
| **Propòsit del compte** | Comprèn l'ús previst del compte | Opció única, Opció múltiple, Text llarg |
| **Titularitat real** | Identifica els titulars reals (UBO) i l'estructura de propietat | Text curt, Número, Pujada de fitxers |
| **Residència fiscal** | Recopila declaracions fiscals | País, Consentiment, Pujada de fitxers |
| **Avaluació de riscos** | Recull informació rellevant sobre el risc | Opció múltiple, Menú desplegable, Text llarg |***## Com funcionaEl nostre flux de treball de qüestionaris està dissenyat per oferir flexibilitat i auditabilitat:### 1. Crea a la consola (sense codi)- Arrossega i deixa anar elements per crear el teu qüestionari
- Organitza el contingut en diverses seccions per a més claredat
- Marca els elements com a obligatoris o opcionals
- Configura textos de marcador de posició i descripcions d'ajuda
- Afegeix opcions (amb seguiment opcional de text lliure) per a menús desplegables i opció única
- Configura els límits de pujada de fitxers/imatges per element### 2. Localitza el contingut- Escriu el contingut una sola vegada en el `default_language` del qüestionari
- Defineix els `languages` admesos: quan publiquis, cada títol, descripció, marcador de posició, etiqueta d'opció i missatge de validació es **tradueix automàticament** a tots ells
- Ajusta qualsevol traducció manualment al constructor; les edicions manuals es conserven fins que canvia el text d'origen
- L'usuari final veu el contingut automàticament en el millor idioma disponible### 3. Publica i recopila- Activa el qüestionari i incrusta'l al teu flux de verificació
- Els usuaris finals completen les seccions i envien les respostes
- Les pujades de fitxers (documents, imatges) s'emmagatzemen i es vinculen a la resposta### 4. Revisa i pren decisions* Les respostes es desen amb un `status`: `Approved`, `In Review` o `Not Finished`
* Pots forçar que totes les respostes del qüestionari passin a `In Review`, perquè una persona les aprovi manualment
* Revisa les respostes i els fitxers a la consola i, tot seguit, marca les respostes com a `Approved`> Nota: Els qüestionaris no generen advertències de risc. La governança s'aconsegueix mitjançant camps obligatoris, validació i fluxos de treball de revisió.***## Capacitats clau| Capacitat | Mode Simple | Mode Avançat |
| - | - | - |
| Constructor d'arrossegar i deixar anar | ✅ | ✅ |
| Camps obligatoris/opcionals | ✅ | ✅ |
| Marcador de posició i descripcions | ✅ | ✅ |
| Múltiples seccions | ✅ | ✅ |
| Límits de pujada de fitxers | ✅ | ✅ |
| Editor visual de grafs | ❌ | ✅ |
| Ramificació condicional | ❌ | ✅ |
| Traduccions multiidioma | ❌ | ✅ |
| Lògica d'opcions (requereix text) | ❌ | ✅ |
| Forçar revisió manual | ❌ | ✅ |
| Compatibilitat amb desfer/refer | ❌ | ✅ |
| Dreceres de teclat | ❌ | ✅ |**Llista completa de funcionalitats:**- **Constructor visual**: crea i gestiona qüestionaris amb un editor intuïtiu d'arrossegar i deixar anar
- **Seccions**: agrupa preguntes relacionades; afegeix encapçalaments i separadors per guiar els usuaris
- **Traduccions automàtiques**: escriu el contingut en un sol idioma; tot el text visible per a l'usuari es tradueix a tots els altres idiomes seleccionats en publicar, amb possibilitat d'ajust manual
- **Validació**: marca camps com a obligatoris; aplica un nombre màxim de fitxers per element de pujada
- **Lògica d'opcions**: per a menús desplegables/opció única, exigeix opcionalment text addicional segons l'opció seleccionada
- **Pujades**: recopila documents i imatges amb límits de nombre de fitxers (per exemple, fins a 3 fitxers)
- **Revisió manual**: força opcionalment totes les respostes a `In Review` pendents d'aprovació humana
- **Commutador d'activació**: activa o desactiva el qüestionari per aplicació
- **Integració de fluxos de treball**: afegeix qüestionaris a KYC o executa'ls de manera independent com a flux de treball de Questionnaire Verification
- **API i webhooks**: llegeix resultats estructurats mitjançant l'API i rep actualitzacions***## Tipus d'elementsPots afegir els següents tipus d'elements al creador (seleccionables des de la consola):### Elements d'entrada| Element | Descripció | Opcions de configuració |
| - | - | - |
| **SHORT\_TEXT** | Text lliure d'una sola línia | Marcador de posició, obligatori |
| **LONG\_TEXT** | Text lliure multilínia | Marcador de posició, obligatori |
| **NUMBER** | Entrada numèrica | Marcador de posició, obligatori |
| **EMAIL** | Entrada de correu electrònic amb validació | Marcador de posició, obligatori |
| **PHONE** | Entrada de número de telèfon | Marcador de posició, obligatori |
| **ADDRESS** | Entrada d'adreça | Marcador de posició, obligatori |
| **DATE\_PICKER** | Selecció de data | Marcador de posició, obligatori |
| **TIME** | Entrada d'hora | Marcador de posició, obligatori |### Elements de selecció| Element | Descripció | Opcions de configuració |
| - | - | - |
| **DROPDOWN** | Selecció única d'una llista | Opcions, `requires_text_input` per opció |
| **SINGLE\_CHOICE** | Selecció única amb estil de botons d'opció | Opcions, `requires_text_input` per opció |
| **MULTIPLE\_CHOICE** | Llista de selecció múltiple | Opcions |
| **COUNTRY** | Selector de país | Obligatori |
| **CONSENT** | Casella de selecció o confirmació | Obligatori, etiqueta personalitzada |### Elements de càrrega| Element | Descripció | Opcions de configuració |
| - | - | - |
| **IMAGE** | Càrrega d'imatges | `max_files` (1-5), obligatori |
| **FILE\_UPLOAD** | Càrrega de documents | `max_files` (1-5), obligatori |### Elements de disseny| Element | Descripció | Notes |
| - | - | - |
| **PARAGRAPH** | Text explicatiu de només lectura | No es pot respondre |
| **SECTION\_HEADER** | Encapçalament visual de secció | No es pot respondre, no obligatori |
| **SEPARATOR** | Separador visual | No es pot respondre, no obligatori |**Notes de comportament:**- `SECTION_HEADER` i `SEPARATOR` són només de presentació. Ignoren l'obligatorietat, el marcador de posició, les opcions i els límits de fitxers.
- Per als elements de selecció, defineix les opcions com a `{ label, value, requires_text_input? }`.
- Per als elements de càrrega, defineix `max_files` (1–5) per controlar quants fitxers es poden adjuntar.***## Forçar la revisió manualAlguns fluxos de treball de compliment requereixen la revisió humana de cada resposta. Des de la consola, pots configurar els qüestionaris perquè el resultat sigui sempre `In Review`. Aleshores, un revisor aprova o sol·licita canvis, després de la qual cosa la resposta passa a ser `Approved`.**Quan utilitzar la revisió manual:**- Alta de clients d'alt risc
- Recollida de dades sensibles (origen dels fons, declaracions d'UBO)
- Requisits normatius de supervisió humana
- Assegurament de la qualitat durant el desplegament inicial***## Exemples de casos d'ús### Origen dels fonsRegistra fonts d'ingressos, imports i puja documents justificatius (p. ex., nòmines, extractes). Combina desplegables, text llarg i càrregues de fitxers.**Estructura típica:**- Secció 1: Situació laboral (Desplegable)
- Secció 2: Fonts d'ingressos (Selecció múltiple + Text llarg)
- Secció 3: Documents justificatius (Càrrega de fitxers)
- Secció 4: Declaració (Consentiment)***### Associació o afiliacióRegistra afiliacions, rols i comprovants de pertinença; inclou elements de consentiment per a les declaracions.**Estructura típica:**- Nom de l'organització (Text curt)
- Rol/Càrrec (Desplegable)
- Durada de l'afiliació (Selector de data)
- Comprovant d'afiliació (Càrrega de fitxers)
- Declaració (Consentiment)***### Objectiu de la relació i activitat prevista del compteRecull la intenció, els volums previstos de transaccions, els països d'activitat i les contraparts previstes. Utilitza selecció única/múltiple, entrades numèriques i paràgrafs per al context.**Estructura típica:**- Secció 1: Propòsit del compte (Selecció múltiple)
- Secció 2: Volum mensual previst (Número + Desplegable per a la divisa)
- Secció 3: Països d'activitat (País - múltiple)
- Secció 4: Tipus de transaccions (Selecció múltiple)
- Secció 5: Informació addicional (Text llarg)***## Mode simple vs. mode avançat: quan utilitzar cadascun| Escenari | Mode recomanat |
| - | - |
| Formulari bàsic en un sol idioma | Simple |
| Necessitat de suport per a diversos idiomes | Avançat |
| Enquesta interna ràpida | Simple |
| Qüestionari de compliment | Avançat |
| Recollida puntual de dades | Simple |
| Camins de ramificació condicional | Avançat |
| Forçar la revisió manual | Avançat |
| Formularis complexos amb múltiples seccions | Avançat |***## Primers passos1. **Ets nou amb els qüestionaris?** Comença amb el **Mode simple** per aprendre a utilitzar el creador
2. **Necessites traduccions o lògica condicional?** Canvia al **Mode avançat** per utilitzar l'editor de graf visual> Consulta com s'estructuren els resultats a la pàgina de l'[Informe de Qüestionaris](https://docs.didit.me/ca/core-technology/questionnaires/report-questionnaire.md).


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