> ## 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. # 電話番号認証レポート：OTPとキャリア情報のJSON > Diditの電話番号認証レスポンスの解析方法：キャリア情報、回線種別、OTPのライフサイクル、セッション間の一致、リスク警告。OTP1件あたり$0.02から＋キャリア手数料の従量課金。 電話番号検証レポートには、電話番号OTP認証の結果がすべて記録されます。コードの送信先、処理を担当したキャリアとチャネル、要した試行回数、番号が使い捨てかVoIPか、ブロックリストや他のユーザーのセッションとのセッション横断的な一致の有無が含まれます。 このページでは、判定エンドポイントが返すJSONの構造を説明します。検証済みの各番号について、OTPの結果、キャリアのメタデータ、リスクフラグを解析する際に参照してください。 ![OTPの結果、キャリアのメタデータ、リスクフラグを表示したDiditの電話番号検証レポート](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=9b5c6c6112303ebc60c0f287aafdb996) ## 概要 電話番号レポートは、ワークフローのノードが電話番号検証機能を実行するたびに生成されます。各レポートは1つの電話番号に対する1回のOTP認証を表し、次の情報を含みます。 * プレフィックス、国内番号、完全なE.164形式に分解した電話番号と、ISO国コードおよび国名。 * 宛先ネットワークから取得したキャリアのメタデータ（`name`、`type`）。 * 回線種別の分析から導出したブール値のリスクフラグ（`is_disposable`、`is_virtual`）。 * 実際に使用された配信チャネル（`verification_method`）と、OTP送信の試行回数。 * すべての送信、再試行、配信イベント、コード確認の試行を時系列で記録した`lifecycle[]`ログ。 * 同じ番号が他のセッション（KYC、KYB、スタンドアロンのAPI検証を問わず、ステータスも問わない）またはブロックリストに存在する場合にそれを示す`matches[]`配列。 * 検証中に発生したリスクイベントを示す`warnings[]`配列（[電話番号検証の警告](https://docs.didit.me/ja/core-technology/phone-verification/warnings-phone-verification.md)を参照）。 * レポートを生成したワークフローグラフのノードを識別する`node_id`（V3セッションのみ）。 ホスト型検証フローでは、DiditがOTPのやり取りを代行します。APIによる直接連携の場合、同じフローは2回の呼び出しで構成されます。コードを配信する[`POST /v3/phone/send/`](https://docs.didit.me/ja/standalone-apis/phone-send)と、ユーザーの入力を検証する[`POST /v3/phone/check/`](https://docs.didit.me/ja/standalone-apis/phone-check)です。保留中のOTPは**最初の送信から5分間**有効です（再試行しても有効期間は延長されません）。ワークフローのセッションでは、デフォルトでユーザーにOTP送信の試行が2回（`phone_max_retries`）、コード入力の試行が2回（`phone_max_check_attempts`）与えられます。いずれもワークフローのノードごとに調整できます。どちらかの上限に達すると、ステップは`VERIFICATION_CODE_ATTEMPTS_EXCEEDED`とともに`Declined`として確定します。スタンドアロンの電話番号APIでは、認証1件あたりコード入力の試行が3回まで許可されます。 ## APIレスポンス内での位置 判定エンドポイント（`GET /v3/session/{sessionId}/decision/`）は、電話番号レポートを複数形の配列キー**`phone_verifications`**の下に返します。この配列には、ワークフローグラフ内の電話番号検証ノードごとに1件のエントリが含まれます。通常は1件ですが、ステップアップフローでは複数件になる場合があります。 ```json theme={null} { "session_id": "11111111-1111-1111-1111-111111111111", "status": "Approved", "phone_verifications": [ { "status": "Approved", "node_id": "feature_phone_1", "...": "..." } ] } ``` 値が`null`の場合、電話番号検証ステップがまだ実行されていないことを意味します。ワークフローで複数の電話番号を収集する可能性がある場合は、（`phone_verifications[0]`を読み取るのではなく）配列を反復処理してください。 ## スキーマ フィールドごとの正式なスキーマは[データモデル](https://docs.didit.me/ja/reference/data-models.md#電話番号検証)ページにあります。 ```typescript theme={null} interface PhoneVerification { status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired"; phone_number_prefix: string; // E.g. "+34" phone_number: string; // National number, no prefix full_number: string; // Full E.164, e.g. "+34600600600" country_code: string; // ISO 3166-1 alpha-2, e.g. "ES" country_name: string; carrier: { name: string; type: // From LineTypeChoices | "mobile" | "fixed_line" | "voip" | "isp" | "vpn" | "toll_free" | "premium_rate" | "shared_cost" | "local_rate" | "satellite" | "pager" | "payphone" | "voice_mail" | "calling_cards" | "service" | "short_codes_commercial" | "universal_access" | "other" | "unknown"; }; is_disposable: boolean; // Temporary / burner number is_virtual: boolean; // true when carrier.type is voip, isp or vpn verification_method: // Actual channel that delivered the OTP | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo"; verification_attempts: number; // OTP send attempts (initial send + resends) verified_at: string | null; // ISO 8601, set when a valid OTP was entered warnings: Warning[]; // Risk events emitted during verification lifecycle: PhoneLifecycleEvent[]; // OTP send/retry/delivery/check timeline matches: PhoneMatch[]; // Cross-session / blocklist matches (max 5) node_id: string; // Workflow graph node that produced this report } ``` ### ステータス値 | ステータス | 意味 | | - | - | | `Not Finished` | OTPの送信は開始されていますが、検証はまだ確定していません。 | | `Approved` | ユーザーが有効なOTPを入力し、却下につながるリスクに該当しませんでした。 | | `Declined` | 自動却下の警告(ブロックリスト、高リスク、試行回数超過)が発生したか、`DECLINE`に設定されたリスクアクションに該当しました。 | | `In Review` | `REVIEW`に設定されたリスクアクションにより、ステップが手動レビューに回されました。 | | `Expired` | 有効なコードが入力されないまま5分間のOTP有効時間が経過しました。スタンドアロンの電話番号APIで作成された検証に適用されます。 | ### ライフサイクルイベントの種類 `lifecycle[]`は時系列順に並びます。各イベントには`type`、`timestamp`、`details`、および課金対象の`fee`(該当する場合)が含まれます。 | イベントの種類 | 発行されるタイミング | | - | - | | `PHONE_VERIFICATION_MESSAGE_SENT` | 要求されたチャネルで最初にOTPの送信を試みたとき。 | | `PHONE_VERIFICATION_RETRY_MESSAGE_SENT` | ユーザーが再送信を要求した後に、OTPを再度送信したとき。 | | `PHONE_VERIFICATION_BLOCKED` | 送信がブロックされたとき(スパム、不審、繰り返し、無効な番号)。 | | `PHONE_DELIVERY_DELIVERED` | 実際に使用されたチャネルでの配信をキャリアが確認したとき。 | | `PHONE_DELIVERY_UNDELIVERABLE` | メッセージを配信できなかったとキャリアが報告したとき。 | | `VALID_CODE_ENTERED` | ユーザーが正しいOTPコードを入力したとき。 | | `INVALID_CODE_ENTERED` | ユーザーが誤ったOTPコードを入力したとき(コード入力回数の上限にカウントされます)。 | | `PHONE_VERIFICATION_APPROVED` | 機能レベルのステータスが`Approved`に設定されたとき。 | | `PHONE_VERIFICATION_DECLINED` | 機能レベルのステータスが`Declined`に設定されたとき。 | | `PHONE_VERIFICATION_IN_REVIEW` | 機能レベルのステータスが`In Review`に設定されたとき。 | | `PHONE_VERIFICATION_EXPIRED` | 有効なコードが入力されないままOTPの有効時間が経過したとき。 | `details`ペイロードの内容はイベントの系統によって異なります。 * **送信イベント**(`PHONE_VERIFICATION_MESSAGE_SENT`、`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`、`PHONE_VERIFICATION_BLOCKED`): `{ status, reason, channel, actual_channel }`。`status`は`Success`、`Retry`、`Blocked`のいずれかです。`reason`は送信がブロックされた場合を除き`null`です(ブロック時は`invalid_phone_number`、`repeated_attempts`、`suspicious`、`spam`、`unknown`)。`channel`は要求されたチャネル、`actual_channel`は実際に配信したチャネルです(例: SMSにフォールバックしたWhatsApp送信)。 * **配信イベント**(`PHONE_DELIVERY_DELIVERED`、`PHONE_DELIVERY_UNDELIVERABLE`): `{ channel, status }`。`status`は`delivered`または`undeliverable`です。 * **チェックイベント**(`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`): `{ code_tried, status }`。`status`は`Approved`、`Declined`、`Failed`、`Expired or Not Found`のいずれかです。 * **最終ステータスイベント**: `null`です。ただし`PHONE_VERIFICATION_DECLINED` / `PHONE_VERIFICATION_IN_REVIEW`は例外で、`{ "reason": "" }`(例: `PHONE_NUMBER_IN_BLOCKLIST`)を含みます。 送信イベントの`fee`は、その送信の合計料金です。キャリアまたはWhatsAppの料金に$0.02のDidit手数料を加えた金額で、[自社のWhatsApp Business番号](https://docs.didit.me/ja/core-technology/phone-verification/overview.md#自社の番号からwhatsappコードを送信する)から送信したWhatsAppコードの場合は$0.02のDidit手数料のみです。配信が確認されるまでは見積もり料金で、確認後は実際の請求額になります。無料が保証されるのは`Blocked`の送信のみです。それ以外の送信は、配信が一度も確認されなかった場合やメッセージが配信不能だった場合でも、検証が確定または期限切れになった時点で課金されます。配信、チェック、ステータスの各イベントは常に`fee: 0`です。 ### セッション間の一致 `matches[]`には、同じアプリケーション内で同じ番号が使用された他のセッションが記録されます。対象はKYC、KYB、スタンドアロンAPIによる検証のすべてで、ステータスは問いません。さらに、[Management APIのリスト](https://docs.didit.me/ja/management-api/lists/overview.md)で設定したブロックリストへの該当も含まれます。現在のセッションと同じ`vendor_data`を持つセッションは除外され(同一のエンドユーザーが自分自身と一致することはありません)、配列は最大**5**件までです。番号がブロックリストに登録されているものの、一致したセッションのいずれもブロックリストに登録されていない場合は、`source: "list_entry"`を持つ合成エントリ(セッション関連のフィールドはすべて`null`)が配列の先頭に追加されます。 ```typescript theme={null} interface PhoneMatch { session_id: string | null; // null when source = "list_entry" session_number: number | null; vendor_data: string | null; verification_date: string | null; // ISO 8601, creation date of the matched session phone_number: string; status: string | null; // Status of the matched session is_blocklisted: boolean; api_service: string | null; // Set when the matched session came from a standalone API source: "session" | "list_entry"; // "list_entry" = manual blocklist hit } ``` ## 例 ### 承認済み (WhatsApp OTP、携帯電話キャリア) ```json theme={null} { "status": "Approved", "phone_number_prefix": "+34", "phone_number": "600600600", "full_number": "+34600600600", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Orange", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2025-08-24T09:12:39.684292Z", "warnings": [], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:12:30.580554Z", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2025-08-24T09:12:31.000000Z", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:12:39.662157Z", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2025-08-24T09:12:39.684292Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "feature_phone_1" } ``` ### 却下 (ブロックリストに登録されたVoIP番号) ユーザーは有効なOTPを入力しましたが、確定処理で番号がアプリケーションのブロックリストに登録されていることが判明し(自動却下)、VoIPの回線種別にもフラグが付けられました(`voip_number_action`は`NO_ACTION`のままのため、`information`として記録されます)。一致したセッションのいずれもブロックリストに登録されていないため、ブロックリストへの該当は合成された`list_entry`の一致として表示されます。 ```json theme={null} { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "5551234567", "full_number": "+15551234567", "country_code": "US", "country_name": "United States", "carrier": { "name": "VoIP Carrier", "type": "voip" }, "is_disposable": false, "is_virtual": true, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2025-08-24T09:11:10.221340Z", "warnings": [ { "feature": "PHONE", "risk": "PHONE_NUMBER_IN_BLOCKLIST", "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null }, "log_type": "error", "short_description": "Phone number in blocklist", "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.", "node_id": "feature_phone_1" }, { "feature": "PHONE", "risk": "VOIP_NUMBER_DETECTED", "additional_data": null, "log_type": "information", "short_description": "VoIP number detected", "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.", "node_id": "feature_phone_1" } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:11:00.000000Z", "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" }, "fee": 0.0509 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:11:10.221340Z", "details": { "code_tried": "482917", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2025-08-24T09:11:10.350000Z", "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" }, "fee": 0 } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "phone_number": "+15551234567", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ], "node_id": "feature_phone_1" } ``` ## 関連情報 * [電話番号検証の概要](https://docs.didit.me/ja/core-technology/phone-verification/overview.md): 機能の動作、料金、対応チャネル。 * [電話番号検証の警告](https://docs.didit.me/ja/core-technology/phone-verification/warnings-phone-verification.md): すべてのリスクコード、却下のトリガー、設定可能なアクション。 * [データモデル: 電話番号検証](https://docs.didit.me/ja/reference/data-models.md#電話番号検証): フィールドごとの正式なスキーマ。 * [スタンドアロンの電話番号API](https://docs.didit.me/ja/standalone-apis/phone-send.md): `POST /v3/phone/send/`および[`POST /v3/phone/check/`](https://docs.didit.me/ja/standalone-apis/phone-check)エンドポイント。 * [Management API: リスト](https://docs.didit.me/ja/management-api/lists/overview.md): `source: list_entry`で`matches[]`に反映される電話番号のブロックリストを管理します。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.