電話番号認証レポート：OTPとキャリア情報のJSON

電話番号検証レポートには、電話番号OTP認証の結果がすべて記録されます。コードの送信先、処理を担当したキャリアとチャネル、要した試行回数、番号が使い捨てかVoIPか、ブロックリストや他のユーザーのセッションとのセッション横断的な一致の有無が含まれます。このページでは、判定エンドポイントが返すJSONの構造を説明します。検証済みの各番号について、OTPの結果、キャリアのメタデータ、リスクフラグを解析する際に参照してください。

OTPの結果、キャリアのメタデータ、リスクフラグを表示したDiditの電話番号検証レポート

概要

電話番号レポートは、ワークフローのノードが電話番号検証機能を実行するたびに生成されます。各レポートは1つの電話番号に対する1回のOTP認証を表し、次の情報を含みます。

プレフィックス、国内番号、完全なE.164形式に分解した電話番号と、ISO国コードおよび国名。
宛先ネットワークから取得したキャリアのメタデータ（name、type）。
回線種別の分析から導出したブール値のリスクフラグ（is_disposable、is_virtual）。
実際に使用された配信チャネル（verification_method）と、OTP送信の試行回数。
すべての送信、再試行、配信イベント、コード確認の試行を時系列で記録したlifecycle[]ログ。
同じ番号が他のセッション（KYC、KYB、スタンドアロンのAPI検証を問わず、ステータスも問わない）またはブロックリストに存在する場合にそれを示すmatches[]配列。
検証中に発生したリスクイベントを示すwarnings[]配列（電話番号検証の警告を参照）。
レポートを生成したワークフローグラフのノードを識別するnode_id（V3セッションのみ）。

ホスト型検証フローでは、DiditがOTPのやり取りを代行します。APIによる直接連携の場合、同じフローは2回の呼び出しで構成されます。コードを配信するPOST /v3/phone/send/と、ユーザーの入力を検証するPOST /v3/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件ですが、ステップアップフローでは複数件になる場合があります。

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}

値がnullの場合、電話番号検証ステップがまだ実行されていないことを意味します。ワークフローで複数の電話番号を収集する可能性がある場合は、（phone_verifications[0]を読み取るのではなく）配列を反復処理してください。

スキーマ

フィールドごとの正式なスキーマはデータモデルページにあります。

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": "<risk code>" }(例: PHONE_NUMBER_IN_BLOCKLIST)を含みます。

送信イベントのfeeは、その送信の合計料金です。キャリアまたはWhatsAppの料金に$0.02のDidit手数料を加えた金額で、[自社のWhatsApp Business番号](/ja/core-technology/phone-verification/overview#自社の番号からwhatsappコードを送信する)から送信したWhatsAppコードの場合は$0.02のDidit手数料のみです。配信が確認されるまでは見積もり料金で、確認後は実際の請求額になります。無料が保証されるのはBlockedの送信のみです。それ以外の送信は、配信が一度も確認されなかった場合やメッセージが配信不能だった場合でも、検証が確定または期限切れになった時点で課金されます。配信、チェック、ステータスの各イベントは常にfee: 0です。

セッション間の一致

matches[]には、同じアプリケーション内で同じ番号が使用された他のセッションが記録されます。対象はKYC、KYB、スタンドアロンAPIによる検証のすべてで、ステータスは問いません。さらに、Management APIのリストで設定したブロックリストへの該当も含まれます。現在のセッションと同じvendor_dataを持つセッションは除外され(同一のエンドユーザーが自分自身と一致することはありません)、配列は最大5件までです。番号がブロックリストに登録されているものの、一致したセッションのいずれもブロックリストに登録されていない場合は、source: "list_entry"を持つ合成エントリ(セッション関連のフィールドはすべて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、携帯電話キャリア)

{
  "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の一致として表示されます。

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

認証

検証

モニタリング

プラットフォーム

電話番号認証レポート：OTPとキャリア情報のJSON

概要

APIレスポンス内での位置

スキーマ

ステータス値

ライフサイクルイベントの種類

セッション間の一致

例

承認済み (WhatsApp OTP、携帯電話キャリア)

却下 (ブロックリストに登録されたVoIP番号)

関連情報

​概要

​APIレスポンス内での位置

​スキーマ

​ステータス値

​ライフサイクルイベントの種類

​セッション間の一致

​例

​承認済み (WhatsApp OTP、携帯電話キャリア)

​却下 (ブロックリストに登録されたVoIP番号)

​関連情報

概要

APIレスポンス内での位置

スキーマ

ステータス値

ライフサイクルイベントの種類

セッション間の一致

例

承認済み (WhatsApp OTP、携帯電話キャリア)

却下 (ブロックリストに登録されたVoIP番号)

関連情報