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

# アンケートレポート：回答のJSONスキーマ

> Didit のアンケートレポートのリファレンスです。V3 判定レスポンスに含まれるセクション、項目、要素タイプ、条件付き表示、項目ごとの回答を解説します。

アンケートレポートには、ユーザーに表示された構造化フォーム、条件付き分岐でユーザーがたどった経路、表示された各項目への回答が含まれます。レポートはノードごとに返されるため、複数インスタンスのワークフロー（たとえばUBOごとに1つのアンケート）では、各インスタンスにつき1件のエントリーが含まれます。

![構造化された回答、セクション、要素タイプを表示するDidit KYCアンケートレポート](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/questionnaire-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9e483a61e829c6b94dd2dc7592a2c59b)

## 概要

各アンケート回答には次の内容が含まれます。

* ユーザーが閲覧した**アンケートのバージョン**（タイトル、説明、言語、バージョンのメタデータ、セクション）。
* フォームのグラフ内でユーザーが実際にたどった経路上の**表示項目**。条件付きロジックによって非表示になった項目はレスポンスから除外されます。
* 表示された各インタラクティブ項目への**回答**。形式はその項目の`element_type`に対応します。
* 回答全体に対する単一の**ステータス**。

レイアウト要素は回答として扱われず、再構成されます。各`SECTION_HEADER`はセクションの区切りとなり、そのタイトルと説明がセクションの`title`/`description`になります。一方、`HEADING`、`PARAGRAPH`、`SEPARATOR`は`answer`キーを持たない状態で`items[]`に残るため、レポートはユーザーが見たものと同じ視覚的構造を保ちます。

## 表示される場所

アンケート機能が実行された場合、アンケートレポートはKYCセッションとKYBセッションのどちらでも、`GET /v3/session/{sessionId}/decision/`内の配列**`questionnaire_responses[]`**として表示されます。このフィールドは、少なくとも1つのアンケートインスタンスが開始されるまで`null`です。各エントリーには`node_id`が含まれるため、複数インスタンスのワークフローでも、どのグラフステップがそのエントリーを生成したかを区別できます。

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

## 項目の形式

正式なスキーマについては、[データモデルリファレンスのアンケート回答](https://docs.didit.me/ja/reference/data-models.md#アンケートの回答)を参照してください。

```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`要素が`items[]`に含まれることはありません。この要素は新しいセクションを開始し、その`title`と`description`を提供します。

### 要素タイプ

| 要素タイプ | 回答の形式 | 備考 |
| - | - | - |
| `SHORT_TEXT`, `LONG_TEXT` | `{ value: string }` | 自由入力テキスト。 |
| `EMAIL`, `DATE_PICKER`, `TIME` | `{ value: string }` | 形式が指定されたテキスト入力。 |
| `NUMBER` | `{ value: number }` | JSONの数値。サーバー側で数値として検証されます。 |
| `COUNTRY` | `{ value: string }` | ISO 3166-1 alpha-3コード（例: `"ESP"`）。サーバー側で検証されます。 |
| `PHONE` | `{ value: { countryCode, callingCode, number } }` | 構造化された電話番号オブジェクト。 |
| `ADDRESS` | `{ value: { street, streetExtraInfo, city, state, postalCode, country } }` | 構造化された住所オブジェクト。 |
| `DROPDOWN`, `SINGLE_CHOICE` | `{ value: string, text?: string }` | `value`は選択肢の値です。選ばれた選択肢が`requires_text_input: true`を持つ場合、`text`に値が入ります。 |
| `MULTIPLE_CHOICE` | `{ value: string[], text?: string }` | 選択肢の値の配列。 |
| `CONSENT` | `{ value: boolean }` | JSONの真偽値。 |
| `FILE_UPLOAD`, `IMAGE` | `{ files: string[] }` | 各エントリーは事前署名付きURLです。 |
| `REPEATABLE_GROUP` | `{ items: Array<{ [fieldValue]: Answer }> }` | 繰り返し1回につき1つのオブジェクト。各サブフィールドの`value`をキーとし、それぞれの回答オブジェクトを持ちます。 |
| `HEADING`, `PARAGRAPH`, `SEPARATOR` | *（`answer`キーなし）* | 純粋なレイアウト要素。構造を保つために`items[]`に残ります。 |

表示されたインタラクティブ項目のうちユーザーが回答しなかったものは、`"answer": null`として返されます。

### 条件付き表示

アンケートでグラフ（条件付きロジック）が定義されている場合、ユーザーが実際にたどった経路上の項目のみが含まれます。ユーザーが進まなかった分岐によって非表示になった項目は、テンプレートに存在していても`sections[].items`には**含まれません**。表示項目が1つも残らないセクションは、セクションごと除外されます。

## ステータスの値

回答レベルの`status`は3つの値のいずれかです。内部では、基本ステータス（`Approved`、またはワークフローで手動レビューが強制されている場合は`In Review`）に、一致したカスタムステータスルールが、プラットフォーム共通の優先順位 Declined > In Review > Approved で組み合わされます。その後、アンケートレベルの`Declined`の結果は`In Review`に変換され、オペレーターがレビュー時に最終的な判定を行います。

| ステータス | 意味 |
| - | - |
| `Not Finished` | ユーザーがまだアンケートを送信していません。 |
| `In Review` | 送信済みで、手動レビュー待ちです（ワークフローで手動レビューが強制されているか、ステータスルールによって回答がエスカレーションされました）。 |
| `Approved` | 送信済みで、受理されました。 |

## 警告

アンケートが出力する警告コードは1つだけです。この警告は、アンケートノードに設定された**カスタムステータスルール**が回答に該当したときに生成されます。

| タグ | 説明 |
| - | - |
| `CUSTOM_STATUS_RULE_TRIGGERED` | ワークフローのステータスルールがアンケートの回答を評価し、機能のステータスを変更（または確定）しました。 |

警告の`additional_data`には、`field`、`operator`、`rule_value`、`actual_value`、`target_status`、およびルールで定義されている場合は`score`が含まれます。`log_type`はルールの対象ステータスに従い、Declinedの場合は`error`、In Reviewの場合は`warning`、それ以外の場合は`information`になります。

他の機能とは異なり、アンケートのエントリーには`warnings[]`配列が埋め込まれません。トリガーされたルールのログはセッション上に`feature: "QUESTIONNAIRE"`として記録され、Consoleのレビュー画面に表示されます（[法人確認の警告一覧](https://docs.didit.me/ja/business-verification/warnings.md#アンケート)も参照してください。同じコードがKYCセッションにも適用されます）。

## 資金源アンケートの例

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

## 未完了の例

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

ユーザーがアンケートステップに到達したものの、まだ回答を送信していない場合、レスポンスは`status: "Not Finished"`で返され、表示されたすべての項目が`"answer": null`になります。ステップに到達しなかったセッションではエントリーは一切生成されず、インスタンスが存在しない場合、`questionnaire_responses`は`null`のままです。

## 注記

* **ファイルURLには有効期限があります。** `answer.files`のエントリは署名付きURL(デフォルトの有効期間は4時間)です。新しいURLが必要な場合は、判定エンドポイントを再度呼び出してください。
* **ローカライズ。** 項目の`title`、`description`、`placeholder`、選択肢の`label`、およびセクションの`title`/`description`は、アンケートが英語に対応している場合は英語で、それ以外の場合はアンケートの`default_language`で返されます。選択肢の`value`は言語が変わっても一定のため、ビジネスロジックのキーとして安全に使用できます。
* **項目の`description`は要素のヘルプテキストです。** 質問を含むすべての項目に設定でき、設定されていない場合は`null`になります。`SEPARATOR`には設定されません。

## 関連情報

> [card] [アンケートの概要](https://docs.didit.me/ja/core-technology/questionnaires/overview.md)
>
> アンケートを作成し、バージョン管理し、ワークフローに追加する方法。

> [card] [データモデル: アンケート回答](https://docs.didit.me/ja/reference/data-models.md#アンケートの回答)
>
> このオブジェクトのフィールドごとの正規スキーマ。

> [card] [セッションの取得](https://docs.didit.me/ja/sessions-api/retrieve-session.md)
>
> V3判定ペイロードのエンドポイントリファレンス。


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