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

# Fragebogen-Bericht: JSON-Schema der Antworten

> Fragebogen-Berichte von Didit: Abschnitte, Elementtypen, bedingte Sichtbarkeit und Antworten je Element in V3-Entscheidungsantworten.

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](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaire-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9e483a61e829c6b94dd2dc7592a2c59b)

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

```text theme={null}
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](https://docs.didit.me/de/reference/data-models.md#fragebogen-antwort).

```typescript theme={null}
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](https://docs.didit.me/de/business-verification/warnings.md#fragebogen); derselbe Code gilt für KYC-Sitzungen).

## Beispiel – Fragebogen zur Mittelherkunft

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

## Verwandte Themen

> [card] [Übersicht über Fragebögen](https://docs.didit.me/de/core-technology/questionnaires/overview.md)
>
> So erstellen, versionieren und verknüpfen Sie Fragebögen mit einem Workflow.

> [card] [Datenmodelle – Fragebogen-Antwort](https://docs.didit.me/de/reference/data-models.md#fragebogen-antwort)
>
> Kanonisches Feld-für-Feld-Schema für dieses Objekt.

> [card] [Sitzung abrufen](https://docs.didit.me/de/sessions-api/retrieve-session.md)
>
> Endpoint-Referenz für die V3-Entscheidungs-Payload.


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