Report del questionario: schema JSON delle risposte

Il report del questionario contiene il modulo strutturato mostrato a un utente, il percorso seguito attraverso eventuali rami condizionali e la risposta per ciascun elemento visibile. Viene restituito per nodo, quindi i workflow con istanze multiple (ad esempio, un questionario per ciascun UBO) contengono una voce per ogni occorrenza.

Report del questionario KYC di Didit con risposte strutturate, sezioni e tipi di elementi

Panoramica

Ogni risposta al questionario descrive:

La versione del questionario visualizzata dall’utente (titolo, descrizione, lingue, metadati della versione, sezioni).
Gli elementi visibili per il percorso effettivamente seguito dall’utente attraverso il grafo del modulo; gli elementi nascosti dalla logica condizionale vengono esclusi dalla risposta.
La risposta per ogni elemento interattivo visibile, nella struttura corrispondente al suo element_type.
Un singolo stato per la risposta nel suo complesso.

Gli elementi di layout vengono riorganizzati anziché ricevere una risposta: ogni SECTION_HEADER definisce il limite di una sezione (il suo titolo e la sua descrizione diventano title/description della sezione), mentre HEADING, PARAGRAPH e SEPARATOR rimangono in items[] senza la chiave answer, in modo che il report mantenga la stessa struttura visiva vista dall’utente.

Dove appare

Il report del questionario compare come array al plurale questionnaire_responses[] in GET /v3/session/{sessionId}/decision/, sia per le sessioni KYC che KYB, ogni volta che è stata eseguita una funzionalità di questionario. Il campo è null finché non viene avviata almeno un’istanza del questionario. Ciascuna voce include un node_id in modo che i workflow con istanze multiple possano distinguere quale passaggio del grafo l’ha generata.

GET /v3/session/{sessionId}/decision/
  ──▶ { "questionnaire_responses": [ { node_id, questionnaire_id, title, status, sections, … }, … ] }

Struttura degli elementi

Consulta la Risposta al questionario nel riferimento ai modelli di dati per lo schema canonico.

interface QuestionnaireResponse {
  questionnaire_id: string;          // UUID of the questionnaire version that was answered
  title: string;                     // Questionnaire name, as set in the Console
  description: string | null;
  languages: string[];               // Supported language codes
  default_language: string;          // Default language code
  is_active: boolean;
  is_simple_questionnaire: boolean;  // true = flat list, false = branching graph
  questionnaire_group_id: string;    // UUID shared by all versions of the same questionnaire
  version: number;                   // Version number within the group
  published_at: string | null;       // ISO 8601 — when this version was published
  status: "Approved" | "In Review" | "Not Finished";
  sections: Array<{
    title: string | null;            // From the SECTION_HEADER that opens the section
    description: string | null;
    items: QuestionnaireItem[];
  }>;
  node_id: string | null;            // Workflow graph node that ran this questionnaire
}

interface QuestionnaireItem {
  uuid: string;                      // Form element UUID
  value: string;                     // Stable node id of the element within the questionnaire graph
  element_type:
    | "SHORT_TEXT" | "LONG_TEXT"
    | "DROPDOWN" | "SINGLE_CHOICE" | "MULTIPLE_CHOICE"
    | "NUMBER" | "EMAIL" | "PHONE" | "ADDRESS" | "COUNTRY"
    | "DATE_PICKER" | "TIME"
    | "CONSENT"
    | "FILE_UPLOAD" | "IMAGE"
    | "REPEATABLE_GROUP"
    | "HEADING" | "PARAGRAPH" | "SEPARATOR";   // layout-only — no answer key
  is_required: boolean;
  title: string | null;              // Localized
  description: string | null;        // Localized help text, or null when none is set
  placeholder: string | null;        // Localized
  choices: Array<{                   // DROPDOWN / SINGLE_CHOICE / MULTIPLE_CHOICE
    label: string;                   // Localized
    value: string;                   // Stable across languages
    requires_text_input?: boolean;   // Selecting this option triggers a free-text follow-up
  }> | null;
  max_files: number | null;          // FILE_UPLOAD / IMAGE upload cap (1–5)
  required_if: {                     // Conditional requirement rule, or null
    rules: Array<{ field: string; operator: string; value?: unknown }>;
    logic: "and" | "or";
  } | null;
  repeatable_config: {               // REPEATABLE_GROUP only, or null
    min_items?: number;
    max_items?: number;
    item_label?: string;             // Localized
    fields: Array<object>;           // Sub-field definitions (value, element_type, title, …)
  } | null;
  answer?: Answer | null;            // Omitted on HEADING / PARAGRAPH / SEPARATOR; null when unanswered
}

Gli elementi SECTION_HEADER non compaiono mai in items[]: aprono una nuova sezione e ne forniscono title e description.

Tipi di elementi

Tipo di elemento	Struttura della risposta	Note
`SHORT_TEXT`, `LONG_TEXT`	`{ value: string }`	Testo libero.
`EMAIL`, `DATE_PICKER`, `TIME`	`{ value: string }`	Varianti di testo tipizzate.
`NUMBER`	`{ value: number }`	Numero JSON, validato lato server come numerico.
`COUNTRY`	`{ value: string }`	Codice ISO 3166-1 alpha-3 (ad es. `"ESP"`), validato lato server.
`PHONE`	`{ value: { countryCode, callingCode, number } }`	Oggetto telefono strutturato.
`ADDRESS`	`{ value: { street, streetExtraInfo, city, state, postalCode, country } }`	Oggetto indirizzo strutturato.
`DROPDOWN`, `SINGLE_CHOICE`	`{ value: string, text?: string }`	`value` è il valore della scelta; `text` viene compilato quando l’opzione selezionata ha `requires_text_input: true`.
`MULTIPLE_CHOICE`	`{ value: string[], text?: string }`	Array di valori scelti.
`CONSENT`	`{ value: boolean }`	Booleano JSON.
`FILE_UPLOAD`, `IMAGE`	`{ files: string[] }`	Ciascuna voce è un URL pre-firmato.
`REPEATABLE_GROUP`	`{ items: Array<{ [fieldValue]: Answer }> }`	Un oggetto per ripetizione, indicizzato dal `value` di ciascun sottocampo con il rispettivo oggetto risposta.
`HEADING`, `PARAGRAPH`, `SEPARATOR`	(nessuna chiave `answer`)	Solo layout: mantenuti in `items[]` per preservare la struttura.

Un elemento interattivo visibile a cui l’utente non ha mai risposto viene restituito con "answer": null.

Visibilità condizionale

Quando un questionario definisce un grafo (logica condizionale), vengono inclusi solo gli elementi presenti sul percorso effettivamente seguito dall’utente. Un elemento nascosto da un ramo non seguito dall’utente non compare in sections[].items, anche se è presente nel modello. Le sezioni che rimangono senza elementi visibili vengono escluse completamente.

Valori di stato

Il valore di status a livello di risposta è uno di tre valori possibili. Internamente, lo stato di base (Approved, o In Review quando il workflow forza la revisione manuale) viene combinato con eventuali regole di stato personalizzate corrispondenti utilizzando la precedenza valida a livello di piattaforma Declined > In Review > Approved; un esito Declined a livello di questionario viene quindi mappato su In Review affinché gli operatori gestiscano la decisione finale durante la revisione.

Stato	Significato
`Not Finished`	L’utente non ha ancora inviato il questionario.
`In Review`	Inviato e in attesa di revisione manuale (il workflow forza la revisione manuale, oppure una regola di stato ha eseguito l’escalation della risposta).
`Approved`	Inviato e accettato.

Avvisi

I questionari emettono un unico codice di avviso, generato quando una regola di stato personalizzata configurata sul nodo del questionario corrisponde a una risposta:

Tag	Descrizione
`CUSTOM_STATUS_RULE_TRIGGERED`	Una regola di stato del workflow ha valutato una risposta del questionario e ha modificato (o confermato) lo stato della funzionalità.

Il campo additional_data dell’avviso contiene field, operator, rule_value, actual_value, target_status e score se la regola ne definisce uno. Il suo log_type segue lo stato di destinazione della regola: error per Declined, warning per In Review, information altrimenti. A differenza di altre funzionalità, la voce del questionario non include un array warnings[]: i log delle regole attivate vengono registrati sulla sessione sotto feature: "QUESTIONNAIRE" e visualizzati nella schermata di revisione della Console (vedi anche l’elenco degli avvisi per la Verifica aziendale; lo stesso codice si applica alle sessioni KYC).

Esempio — Questionario sull’origine dei fondi

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Approved",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Business Income", "value": "business_income" },
                { "label": "Savings", "value": "savings" },
                { "label": "Investments", "value": "investments" },
                { "label": "Inheritance/Gift", "value": "inheritance_gift" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "salary" }
            },
            {
              "uuid": "2d16b527-72be-42e0-8e96-b164b818386c",
              "value": "question_2",
              "element_type": "LONG_TEXT",
              "is_required": true,
              "title": "Provide details of the primary source.",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "Software engineer at Acme Ltd since 2018." }
            },
            {
              "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa",
              "value": "question_3",
              "element_type": "SINGLE_CHOICE",
              "is_required": true,
              "title": "Will any funds originate from third parties?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Yes", "value": "yes", "requires_text_input": true },
                { "label": "No", "value": "no" }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "yes", "text": "One-off gift from parents, EUR 8,000." }
            },
            {
              "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13",
              "value": "question_4",
              "element_type": "FILE_UPLOAD",
              "is_required": true,
              "title": "Upload a proof of funds document",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 3,
              "required_if": null,
              "repeatable_config": null,
              "answer": {
                "files": [
                  "https://<media-host>/.../payslip-jul.pdf",
                  "https://<media-host>/.../payslip-aug.pdf"
                ]
              }
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

Esempio — Non completato

{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Not Finished",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": null
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}

Quando l’utente ha raggiunto il passaggio del questionario ma non ha ancora inviato le risposte, la risposta viene restituita con status: "Not Finished" e "answer": null su ogni elemento visibile. Una sessione che non ha mai raggiunto il passaggio non produce alcuna voce: questionnaire_responses rimane null quando non esiste alcuna istanza.

Note

Gli URL dei file scadono. Le voci in answer.files sono URL pre-firmati (validità di 4 ore per impostazione predefinita). Richiama l’endpoint della decisione quando hai bisogno di URL aggiornati.
Localizzazione. I campi title, description e placeholder dell’elemento, label della scelta e title/description della sezione vengono restituiti in inglese quando il questionario lo supporta, altrimenti nella default_language del questionario. Il campo value di una scelta rimane stabile tra le diverse lingue, consentendoti di basare la logica di business su di esso in modo sicuro.
Il campo description dell’elemento è il testo di aiuto dell’elemento. Qualsiasi elemento può averne uno, incluse le domande, ed è null quando non ne è impostato alcuno. Un SEPARATOR non ne ha mai uno.

Correlati

Panoramica dei questionari

Come creare, gestire le versioni e allegare questionari a un workflow.

Modelli di dati — Risposta al questionario

Schema canonico campo per campo per questo oggetto.

Recupera sessione

Riferimento dell’endpoint per il payload della decisione V3.

Autenticazione

Verifica

Monitoraggio

Piattaforma

Report del questionario: schema JSON delle risposte

Panoramica

Dove appare

Struttura degli elementi

Tipi di elementi

Visibilità condizionale

Valori di stato

Avvisi

Esempio — Questionario sull’origine dei fondi

Esempio — Non completato

Note

Correlati

Panoramica dei questionari

Modelli di dati — Risposta al questionario

Recupera sessione

​Panoramica

​Dove appare

​Struttura degli elementi

​Tipi di elementi

​Visibilità condizionale

​Valori di stato

​Avvisi

​Esempio — Questionario sull’origine dei fondi

​Esempio — Non completato

​Note

​Correlati

Panoramica dei questionari

Modelli di dati — Risposta al questionario

Recupera sessione

Panoramica

Dove appare

Struttura degli elementi

Tipi di elementi

Visibilità condizionale

Valori di stato

Avvisi

Esempio — Questionario sull’origine dei fondi

Esempio — Non completato

Note

Correlati