Fragebogen-Bericht: JSON-Schema der Antworten

Der Fragebogenbericht enthält das strukturierte Formular, das einem Benutzer angezeigt wurde, den Pfad, den er durch etwaige bedingte Verzweigungen genommen hat, sowie die Antwort für jedes sichtbare Element. Er wird pro Knoten zurückgegeben, sodass Workflows mit mehreren Instanzen (beispielsweise ein Fragebogen pro UBO) einen Eintrag pro Vorkommen enthalten.

Didit KYC-Fragebogenbericht mit strukturierten Antworten, Abschnitten und Elementtypen

Übersicht

Jede Fragebogenantwort beschreibt:

Die Fragebogenversion, die der Benutzer gesehen hat (Titel, Beschreibung, Sprachen, Versionsmetadaten, Abschnitte).
Die sichtbaren Elemente für den Pfad, den der Benutzer tatsächlich durch den Graphen des Formulars genommen hat – durch bedingte Logik ausgeblendete Elemente werden aus der Antwort entfernt.
Die Antwort für jedes sichtbare interaktive Element in der Struktur, die seinem element_type entspricht.
Einen einzelnen Status für die Antwort als Ganzes.

Layoutelemente werden umstrukturiert statt beantwortet: Jedes SECTION_HEADER wird zu einer Abschnittsgrenze (dessen Titel und Beschreibung werden zu title/description des Abschnitts), während HEADING, PARAGRAPH und SEPARATOR ohne answer-Schlüssel in items[] verbleiben, damit der Bericht dieselbe visuelle Struktur beibehält, die der Benutzer gesehen hat.

Wo es erscheint

Der Fragebogenbericht erscheint als Plural-Array questionnaire_responses[] in GET /v3/session/{sessionId}/decision/, sowohl für KYC- als auch KYB-Sitzungen, wann immer eine Fragebogen-Funktion ausgeführt wurde. Das Feld ist null, bis mindestens eine Fragebogen-Instanz gestartet wurde. Jeder Eintrag enthält eine node_id, damit Workflows mit mehreren Instanzen eindeutig bestimmen können, welcher Graph-Schritt ihn erzeugt hat.

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

Elementstruktur

Das kanonische Schema finden Sie unter Fragebogenantwort in der Datenmodell-Referenz.

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
}

SECTION_HEADER-Elemente erscheinen nie in items[] – sie öffnen einen neuen Abschnitt und liefern dessen title und description.

Elementtypen

Elementtyp	Antwortstruktur	Hinweise
`SHORT_TEXT`, `LONG_TEXT`	`{ value: string }`	Freitext.
`EMAIL`, `DATE_PICKER`, `TIME`	`{ value: string }`	Typisierte Textvarianten.
`NUMBER`	`{ value: number }`	JSON-Zahl – serverseitig als numerisch validiert.
`COUNTRY`	`{ value: string }`	ISO-3166-1-Alpha-3-Code (z. B. `"ESP"`), serverseitig validiert.
`PHONE`	`{ value: { countryCode, callingCode, number } }`	Strukturiertes Telefonobjekt.
`ADDRESS`	`{ value: { street, streetExtraInfo, city, state, postalCode, country } }`	Strukturiertes Adressobjekt.
`DROPDOWN`, `SINGLE_CHOICE`	`{ value: string, text?: string }`	`value` ist der ausgewählte Wert; `text` wird ausgefüllt, wenn die gewählte Option `requires_text_input: true` hat.
`MULTIPLE_CHOICE`	`{ value: string[], text?: string }`	Array von Auswahlwerten.
`CONSENT`	`{ value: boolean }`	JSON-Boolean.
`FILE_UPLOAD`, `IMAGE`	`{ files: string[] }`	Jeder Eintrag ist eine vorab signierte URL.
`REPEATABLE_GROUP`	`{ items: Array<{ [fieldValue]: Answer }> }`	Ein Objekt pro Wiederholung, mit dem `value` jedes Unterfelds als Schlüssel und eigenem Antwortobjekt.
`HEADING`, `PARAGRAPH`, `SEPARATOR`	(kein `answer`-Schlüssel)	Reines Layout – bleibt zur Strukturierung in `items[]`.

Ein sichtbares interaktives Element, das der Benutzer nie beantwortet hat, wird mit "answer": null zurückgegeben.

Bedingte Sichtbarkeit

Wenn ein Fragebogen einen Graphen definiert (bedingte Logik), werden nur Elemente auf dem Pfad einbezogen, den der Benutzer tatsächlich genommen hat. Ein Element, das durch eine Verzweigung ausgeblendet wird, der der Benutzer nicht gefolgt ist, erscheint nicht in sections[].items – selbst wenn es in der Vorlage vorhanden ist. Abschnitte, die keine sichtbaren Elemente mehr enthalten, werden vollständig weggelassen.

Statuswerte

Der status auf Antwortebene ist einer von drei Werten. Intern wird der Basisstatus (Approved oder In Review, wenn der Workflow eine manuelle Prüfung erzwingt) mit allen übereinstimmenden benutzerdefinierten Statusregeln gemäß der plattformweiten Rangfolge Declined > In Review > Approved kombiniert; ein Declined-Ergebnis auf Fragebogenebene wird anschließend auf In Review abgebildet, sodass Prüfer die endgültige Entscheidung während der Prüfung treffen.

Status	Bedeutung
`Not Finished`	Der Benutzer hat den Fragebogen noch nicht übermittelt.
`In Review`	Übermittelt und wartet auf manuelle Prüfung (der Workflow erzwingt eine manuelle Prüfung oder eine Statusregel hat die Antwort eskaliert).
`Approved`	Übermittelt und akzeptiert.

Warnungen

Fragebögen geben einen einzelnen Warncode aus, der erzeugt wird, wenn eine auf dem Fragebogen-Knoten konfigurierte benutzerdefinierte Statusregel mit einer Antwort übereinstimmt:

Tag	Beschreibung
`CUSTOM_STATUS_RULE_TRIGGERED`	Eine Workflow-Statusregel hat eine Fragebogenantwort ausgewertet und den Status der Funktion geändert (oder bestätigt).

Das additional_data-Objekt der Warnung enthält field, operator, rule_value, actual_value, target_status und score, sofern die Regel einen solchen definiert. Der log_type der Warnung folgt dem Zielstatus der Regel: error für Declined, warning für In Review, andernfalls information. Anders als bei anderen Funktionen bettet der Fragebogeneintrag kein warnings[]-Array ein – Protokolle ausgelöster Regeln werden in der Sitzung unter feature: "QUESTIONNAIRE" erfasst und in der Prüfungsansicht der Console angezeigt (siehe auch die Übersicht der Warnungen zur Unternehmensverifizierung; derselbe Code gilt für KYC-Sitzungen).

Beispiel – Fragebogen zur Mittelherkunft

{
  "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"
    }
  ]
}

Beispiel – Nicht abgeschlossen

{
  "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"
    }
  ]
}

Wenn der Benutzer den Fragebogenschritt erreicht, aber noch keine Antworten übermittelt hat, wird die Antwort mit status: "Not Finished" und "answer": null bei jedem sichtbaren Element zurückgegeben. Eine Sitzung, die den Schritt nie erreicht hat, erzeugt überhaupt keinen Eintrag – questionnaire_responses bleibt null, wenn keine Instanz existiert.

Hinweise

Datei-URLs laufen ab. Einträge in answer.files sind vorab signierte URLs (standardmäßig 4 Stunden gültig). Rufen Sie den Entscheidungs-Endpoint erneut auf, wenn Sie neue URLs benötigen.
Lokalisierung. Element-title, description, placeholder, Auswahl-label sowie Abschnitts-title/description werden auf Englisch zurückgegeben, sofern der Fragebogen dies unterstützt, andernfalls in der default_language des Fragebogens. Der value einer Auswahl bleibt über Sprachen hinweg unverändert, sodass Sie Ihre Geschäftslogik zuverlässig darauf stützen können.
Element-description ist der Hilfetext des Elements. Jedes Element kann einen besitzen, einschließlich Fragen; wenn keiner festgelegt ist, ist der Wert null. Ein SEPARATOR besitzt nie einen.

Übersicht über Fragebögen

So erstellen, versionieren und verknüpfen Sie Fragebögen mit einem Workflow.

Datenmodelle – Fragebogen-Antwort

Kanonisches Feld-für-Feld-Schema für dieses Objekt.

Sitzung abrufen

Endpoint-Referenz für die V3-Entscheidungs-Payload.

Authentifizierung

Verifizierung

Überwachung

Plattform

Fragebogen-Bericht: JSON-Schema der Antworten

Übersicht

Wo es erscheint

Elementstruktur

Elementtypen

Bedingte Sichtbarkeit

Statuswerte

Warnungen

Beispiel – Fragebogen zur Mittelherkunft

Beispiel – Nicht abgeschlossen

Hinweise

Verwandte Themen

Übersicht über Fragebögen

Datenmodelle – Fragebogen-Antwort

Sitzung abrufen

​Übersicht

​Wo es erscheint

​Elementstruktur

​Elementtypen

​Bedingte Sichtbarkeit

​Statuswerte

​Warnungen

​Beispiel – Fragebogen zur Mittelherkunft

​Beispiel – Nicht abgeschlossen

​Hinweise

​Verwandte Themen

Übersicht über Fragebögen

Datenmodelle – Fragebogen-Antwort

Sitzung abrufen

Übersicht

Wo es erscheint

Elementstruktur

Elementtypen

Bedingte Sichtbarkeit

Statuswerte

Warnungen

Beispiel – Fragebogen zur Mittelherkunft

Beispiel – Nicht abgeschlossen

Hinweise

Verwandte Themen