> ## 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.

# Questionari KYC via API: Generatore di moduli dinamici

> Crea questionari KYC personalizzati con Didit: logica condizionale, multilingua e instradamento alla revisione manuale. Pay-per-call a $0.10.

I Questionari di Didit ti consentono di progettare moduli strutturati e dinamici per raccogliere informazioni aggiuntive dagli utenti durante la verifica. Usa il nostro builder visuale per trascinare e rilasciare elementi, organizzare i contenuti in sezioni, localizzare il testo per più lingue e indirizzare i risultati alla revisione manuale quando necessario.

Prompt per l'integrazione dei Questionari
        Copia il prompt negli appunti



      
      

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



      
      

Incolla in

Nella lezione dell'Academy sulla lettura di un risultato di verifica, il capitolo alle 11:54 tratta Document AI e i questionari.[Document AI e questionari — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=714\&rel=0\&playsinline=1)***## Due modi per creare i questionariDidit offre **due approcci distinti** per la creazione di questionari, consentendoti di scegliere il livello di complessità più adatto alle tue esigenze:![Modalità di creazione semplice e avanzata dei questionari KYC di Didit affiancate](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. Modalità semplice: builder rapido di moduliLa **Modalità semplice** è ideale per creare moduli lineari in modo rapido. Utilizza la nostra intuitiva interfaccia drag-and-drop per aggiungere elementi, impostare i campi obbligatori e pubblicare in pochi minuti.![Interfaccia drag-and-drop del builder di questionari in modalità semplice di 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)**Ideale per:**- Moduli rapidi per la raccolta dati
- Sondaggi semplici e attestazioni
- Team alle prime armi con la creazione di moduli
- Questionari in un'unica lingua**Come funziona:**1) Apri il Questionnaire Builder
2) Trascina gli elementi dalla tavolozza sul tuo modulo
3) Configura ciascun elemento (etichetta, obbligatorio, segnaposto)
4) Visualizza l'anteprima e pubblica***### 2. Modalità avanzata: visual graph builderLa **Modalità avanzata** sblocca potenti funzionalità per scenari complessi di raccolta dati utilizzando un **editor visivo basato su nodi**. Crea questionari sofisticati con logica condizionale, percorsi di diramazione e un controllo completo sul flusso.![Editor visivo basato su nodi del grafo per questionari avanzati di Didit con logica di diramazione](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)**Ideale per:**- Questionari multilingue
- Moduli complessi con ramificazione condizionale
- Raccolta dati orientata alla compliance con percorsi diversi
- Moduli che richiedono workflow di revisione manuale**Funzionalità chiave:**- **Editor visivo dei nodi**: trascina, rilascia e collega i nodi su un canvas infinito
- **Connessioni intelligenti**: trascina dal punto di aggancio di un nodo verso uno spazio vuoto per creare e collegare istantaneamente un nuovo nodo
- **Ramificazione condizionale**: indirizza gli utenti verso domande diverse in base alle risposte precedenti, per poi [riunire i percorsi in un passaggio condiviso](#riunire-i-percorsi-di-diramazione-in-un-passaggio-condiviso)
- **Supporto multilingue**: traduci tutti i contenuti visibili all'utente
- **Scorciatoie da tastiera**: Annulla (Ctrl/Cmd+Z), Ripeti (Ctrl/Cmd+Shift+Z), Elimina (Canc/Backspace)
- **Zoom e panoramica**: naviga nei moduli complessi con lo scorrimento per lo zoom e il trascinamento per la panoramica#### Tipi di nodi del Graph Builder| Tipo di nodo | Colore | Descrizione | Quando usarlo |
| - | - | - | - |
| **Nodi domanda** | Blu | Elementi di input che raccolgono i dati dell'utente | Campi di testo, menu a discesa, caricamento file, date, ecc. |
| **Nodi di testo** | Verde | Contenuti di sola lettura mostrati agli utenti | Istruzioni, spiegazioni, testi legali |
| **Nodi di diramazione** | Arancione | Instradamento condizionale basato sulle risposte | "Se il paese è US, mostra il modulo fiscale" |
| **Nodi di sezione** | Grigio | Raggruppamento visivo di elementi correlati | Organizzare le domande in sezioni logiche |> **Regole di connessione:** i nodi di sezione e di testo possono connettersi ai nodi domanda e ad altri nodi di testo, ma non direttamente ai nodi di diramazione. I nodi di diramazione possono connettersi a qualsiasi tipo di nodo.#### Operatori di condizioneUna condizione di diramazione confronta una risposta precedente con un valore.
Combina più condizioni con `and` o `or`.| Operatore | Corrisponde quando la risposta |
| - | - |
| `equals` | È uguale al valore |
| `not_equals` | Non è uguale al valore |
| `contains` | Contiene il valore |
| `greater_than` | È maggiore del valore |
| `greater_than_or_equals` | È maggiore o uguale al valore |
| `less_than` | È minore del valore |
| `less_than_or_equals` | È minore o uguale al valore |
| `in` | Fa parte di un elenco di valori |
| `not_in` | Non fa parte di un elenco di valori |
| `is_empty` | È stata lasciata vuota |
| `is_not_empty` | È stata compilata |#### Riunire i percorsi di diramazione in un passaggio condivisoLa diramazione non deve necessariamente restare a senso unico. Il termine di più percorsi può collegarsi allo stesso nodo a valle e il questionario prosegue da lì una sola volta. Le domande condivise vengono create e gestite in un unico punto, anziché essere ripetute alla fine di ogni percorso.**Esempio pratico: domande aggiuntive in caso di Sì, poi una coda condivisa**1) Aggiungi un **nodo domanda** con una domanda a **Scelta Singola** che propone Sì e No, quindi aggiungi un **nodo di diramazione** successivo con un percorso `Yes` e un percorso `No`.
2) Sul percorso `Yes`, aggiungi le domande supplementari che si applicano solo quando la risposta è Sì.
3) Alla fine di quel percorso, aggiungi la prima domanda a cui ogni rispondente deve rispondere dopo la diramazione: l'inizio della coda condivisa.
4) Indirizza il percorso `No` verso quella domanda: apri il menu **+** alla fine del percorso `No` e scegli **Collega un passaggio esistente**, oppure trascina dal connettore del percorso `No` e rilascia sul bordo superiore della domanda condivisa. Il canvas si collega solo al piccolo punto di aggancio nella parte superiore della scheda; pertanto, rilasciando al centro della scheda non accadrà nulla.
5) Continua ad aggiungere le restanti domande condivise dopo la prima, quindi pubblica. Il canvas disegna la coda condivisa una sola volta, al di sotto dei percorsi che conducono ad essa.Un percorso può unirsi a un nodo già esistente in questo modo, e più percorsi possono puntare allo stesso nodo. L'unione definisce dove prosegue quel percorso, quindi il menu **+** propone **Collega un passaggio esistente** finché il percorso termina lì. Una connessione che creerebbe un ciclo all'indietro verso un nodo precedente viene rifiutata.I rispondenti rispondono alle domande condivise una sola volta, qualunque sia il percorso seguito; le domande presenti sul percorso non intrapreso vengono saltate. Il payload della decisione segue la stessa regola: `questionnaire_responses[].sections[].items` elenca solo le voci del percorso seguito dal rispondente. Consulta [Visibilità condizionale](https://docs.didit.me/it/core-technology/questionnaires/report-questionnaire.md#visibilità-condizionale).***## Modelli di questionarioI modelli ti aiutano a iniziare rapidamente con moduli preconfigurati per i casi d'uso più comuni. Puoi usarli così come sono o personalizzarli in base alle tue esigenze.![Modelli predefiniti di questionari Didit per origine dei fondi e conformità 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)### Modelli predefiniti| Modello | Descrizione | Elementi tipici |
| - | - | - |
| **Origine dei fondi** | Raccogli fonti di reddito e documentazione di supporto | Menu a discesa, Testo lungo, Caricamento file |
| **Dettagli sull'impiego** | Raccogli posizione lavorativa, datore di lavoro, fascia di reddito | Testo breve, Menu a discesa, Numero |
| **Scopo dell'account** | Comprendi l'uso previsto dell'account | Scelta singola, Scelta multipla, Testo lungo |
| **Assetto proprietario** | Identifica i titolari effettivi (UBO) e l'assetto proprietario | Testo breve, Numero, Caricamento file |
| **Residenza fiscale** | Raccogli dichiarazioni di natura fiscale | Paese, Consenso, Caricamento file |
| **Valutazione del rischio** | Raccogli informazioni rilevanti per il rischio | Scelta multipla, Menu a discesa, Testo lungo |***## Come funzionaIl nostro workflow di questionari è progettato per offrire flessibilità e possibilità di audit:### 1. Creazione nella console (senza codice)- Trascina e rilascia gli elementi per creare il tuo questionario
- Organizza i contenuti in più sezioni per maggiore chiarezza
- Contrassegna gli elementi come obbligatori o facoltativi
- Configura placeholder e descrizioni di supporto
- Aggiungi opzioni (con testo libero aggiuntivo facoltativo) per menu a discesa e scelta singola
- Configura i limiti di caricamento file/immagini per ciascun elemento### 2. Localizzazione dei contenuti- Scrivi i tuoi contenuti una sola volta nella lingua predefinita (`default_language`) del questionario
- Definisci le lingue supportate (`languages`): al momento della pubblicazione, ogni titolo, descrizione, placeholder, etichetta di opzione e messaggio di convalida viene **tradotto automaticamente** in tutte le lingue
- Perfeziona manualmente qualsiasi traduzione nel builder; le modifiche manuali vengono conservate finché il testo di origine non cambia
- L'utente finale visualizza automaticamente i contenuti nella migliore lingua disponibile### 3. Pubblicazione e raccolta- Attiva il questionario e incorporalo nel tuo flusso di verifica
- Gli utenti finali completano le sezioni e inviano le risposte
- I caricamenti di file (documenti, immagini) vengono archiviati e collegati alla risposta### 4. Revisione e decisione* Le risposte vengono salvate con uno stato (`status`): `Approved`, `In Review` o `Not Finished`
* Puoi forzare lo stato di tutte le risposte al questionario su `In Review`, in modo che una persona le approvi manualmente
* Esamina risposte e file nella console, quindi contrassegna come `Approved`> Nota: I questionari non generano avvisi di rischio. La governance viene garantita tramite campi obbligatori, convalida e workflow di revisione.***## Funzionalità principali| Funzionalità | Modalità semplice | Modalità avanzata |
| - | - | - |
| Editor con trascinamento | ✅ | ✅ |
| Campi obbligatori/facoltativi | ✅ | ✅ |
| Placeholder e descrizioni | ✅ | ✅ |
| Più sezioni | ✅ | ✅ |
| Limiti di caricamento file | ✅ | ✅ |
| Editor grafico visuale | ❌ | ✅ |
| Ramificazioni condizionali | ❌ | ✅ |
| Traduzioni multilingue | ❌ | ✅ |
| Logica delle opzioni (testo obbligatorio) | ❌ | ✅ |
| Forza la revisione manuale | ❌ | ✅ |
| Supporto per Annulla/Ripristina | ❌ | ✅ |
| Scorciatoie da tastiera | ❌ | ✅ |**Elenco completo delle funzionalità:**- **Builder visuale**: Crea e gestisci questionari con un editor intuitivo con trascinamento
- **Sezioni**: Raggruppa domande correlate; aggiungi intestazioni e separatori per guidare gli utenti
- **Traduzioni automatiche**: Scrivi i contenuti in una lingua: tutto il testo visibile all'utente viene tradotto in ogni altra lingua selezionata al momento della pubblicazione, con supporto per il perfezionamento manuale
- **Convalida**: Contrassegna i campi come obbligatori; imposta il numero massimo di file per elemento di caricamento
- **Logica delle opzioni**: Per menu a discesa/scelta singola, richiedi facoltativamente testo aggiuntivo per ciascuna opzione selezionata
- **Caricamenti**: Raccogli documenti e immagini con limiti sul numero di file (ad es. fino a 3 file)
- **Revisione Manuale**: Facoltativamente, forza tutte le risposte su `In Review` in attesa dell'approvazione umana
- **Attivazione/Disattivazione**: Abilita o disabilita il questionario per ogni applicazione
- **Integrazione nei workflow**: Aggiungi questionari al KYC o eseguili in modo autonomo come workflow di verifica con questionario
- **API e webhook**: Leggi i risultati strutturati tramite API e ricevi aggiornamenti***## Tipi di elementoNel costruttore puoi aggiungere i seguenti tipi di elemento (selezionabili dalla console):### Elementi di input| Elemento | Descrizione | Opzioni di configurazione |
| - | - | - |
| **SHORT\_TEXT** | Testo libero a riga singola | Segnaposto, obbligatorio |
| **LONG\_TEXT** | Testo libero multilinea | Segnaposto, obbligatorio |
| **NUMBER** | Campo numerico | Segnaposto, obbligatorio |
| **EMAIL** | Campo email con validazione | Segnaposto, obbligatorio |
| **PHONE** | Campo per il numero di telefono | Segnaposto, obbligatorio |
| **ADDRESS** | Campo per l'indirizzo | Segnaposto, obbligatorio |
| **DATE\_PICKER** | Selezione della data | Segnaposto, obbligatorio |
| **TIME** | Campo per l'orario | Segnaposto, obbligatorio |### Elementi di scelta| Elemento | Descrizione | Opzioni di configurazione |
| - | - | - |
| **DROPDOWN** | Selezione singola da un elenco | Scelte, `requires_text_input` per scelta |
| **SINGLE\_CHOICE** | Selezione singola con pulsanti radio | Scelte, `requires_text_input` per scelta |
| **MULTIPLE\_CHOICE** | Checklist a selezione multipla | Scelte |
| **COUNTRY** | Selettore del paese | Obbligatorio |
| **CONSENT** | Casella di controllo o attestazione | Obbligatorio, etichetta personalizzata |### Elementi di caricamento| Elemento | Descrizione | Opzioni di configurazione |
| - | - | - |
| **IMAGE** | Caricamento di immagini | `max_files` (1-5), obbligatorio |
| **FILE\_UPLOAD** | Caricamento di documenti | `max_files` (1-5), obbligatorio |### Elementi di layout| Elemento | Descrizione | Note |
| - | - | - |
| **PARAGRAPH** | Testo esplicativo di sola lettura | Non compilabile |
| **SECTION\_HEADER** | Intestazione visiva di sezione | Non compilabile, non obbligatorio |
| **SEPARATOR** | Separatore visivo | Non compilabile, non obbligatorio |**Note sul comportamento:**- `SECTION_HEADER` e `SEPARATOR` servono solo per la presentazione. Ignorano le impostazioni di obbligatorietà, i segnaposto, le scelte e i limiti sui file.
- Per gli elementi di scelta, definisci le opzioni come `{ label, value, requires_text_input? }`.
- Per gli elementi di caricamento, imposta `max_files` (1–5) per stabilire quanti file è possibile allegare.***## Forzare la revisione manualeAlcuni workflow di compliance richiedono la revisione umana per ogni risposta. Dalla console puoi configurare i questionari in modo che abbiano sempre come esito `In Review`. Un revisore approva quindi la risposta o richiede modifiche, dopodiché lo stato passa ad `Approved`.**Quando utilizzare la revisione manuale:**- Onboarding di clienti ad alto rischio
- Raccolta di dati sensibili (origine dei fondi, dichiarazioni UBO)
- Requisiti normativi che impongono la supervisione umana
- Controllo di qualità durante il rilascio iniziale***## Esempi di casi d'uso### Origine dei fondiRaccogli fonti di reddito, importi e fai caricare documenti giustificativi (ad es. buste paga, estratti conto). Puoi combinare menu a discesa, testo lungo e caricamento di file.**Struttura tipica:**- Sezione 1: Stato occupazionale (Dropdown)
- Sezione 2: Fonti di reddito (Multiple Choice + Long Text)
- Sezione 3: Documenti giustificativi (File Upload)
- Sezione 4: Dichiarazione (Consent)***### Associazione o adesioneRegistra affiliazioni, ruoli e attestazioni di iscrizione; includi elementi di consenso per le dichiarazioni.**Struttura tipica:**- Nome dell'organizzazione (Short Text)
- Ruolo/Posizione (Dropdown)
- Durata dell'iscrizione (Date Picker)
- Attestazione di iscrizione (File Upload)
- Dichiarazione (Consent)***### Scopo del rapporto e attività prevista sul contoRaccogli le finalità, i volumi previsti delle transazioni, i paesi in cui si opera e le controparti previste. Utilizza scelte singole o multiple, campi numerici e paragrafi per contestualizzare.**Struttura tipica:**- Sezione 1: Scopo del conto (Multiple Choice)
- Sezione 2: Volume mensile previsto (Number + Dropdown per la valuta)
- Sezione 3: Paesi di operatività (Country - selezione multipla)
- Sezione 4: Tipologie di transazione (Multiple Choice)
- Sezione 5: Informazioni aggiuntive (Long Text)***## Modalità semplice o avanzata: quale scegliere| Scenario | Modalità consigliata |
| - | - |
| Modulo base, in un'unica lingua | Simple |
| Necessità di supporto multilingua | Advanced |
| Rapido sondaggio interno | Simple |
| Questionario di compliance | Advanced |
| Raccolta dati una tantum | Simple |
| Percorsi di diramazione condizionali | Advanced |
| Revisione manuale obbligatoria | Advanced |
| Moduli complessi su più sezioni | Advanced |***## Per iniziare1. **Non hai mai usato i questionari?** Parti dalla **Simple Mode** per familiarizzare con il costruttore
2. **Ti servono traduzioni o logica condizionale?** Passa alla **Advanced Mode** per utilizzare l'editor visuale del grafo> Scopri come sono strutturati i risultati nella pagina del [report dei questionari](https://docs.didit.me/it/core-technology/questionnaires/report-questionnaire.md).


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