didit-phone-verification について
電話番号の認証やリスク確認が必要なアプリ向けに、Didit API の単独エンドポイントを案内するスキルです。コードの送信・照合と電話番号のリスク情報取得を扱います。
主な機能
- 01対応チャネルでワンタイムコードを送信
- 02コードを照合して電話番号レポートを取得
- 03コード送信なしで電話番号のリスクを評価
- 04キャリア、回線種別、不正利用シグナルを確認
活用シーン
- 01登録時の電話番号確認
- 02使い捨て番号、VoIP、重複番号の検出
- 03アカウント操作前の電話番号リスク確認
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/didit-phone-verificationを入力して読み込まれたか確認します。
同梱ファイルscripts/verify_phone.py
詳細
Didit 電話番号確認 API
概要
単独で利用できる3つのエンドポイント：
- 電話番号にワンタイムコードを送信：
POST /v3/phone/send/ - ユーザーが入力したコードを確認し、電話番号レポートを取得：
POST /v3/phone/check/ - リスク（コードは送信しません）：1回の呼び出しで電話番号をスコアリング：
POST /v3/phone/risk/
主な制約（送信と確認）：
- 電話番号は E.164 形式（例：
+14155552671）で指定します。検証および正規化が行われ、無効な番号には400が返されます。 - 確認では、お客様のアプリケーションと
phone_numberを使って確認レコードを検索します。request_idは指定しません。 - 保留中の確認の有効期間は、最初の送信から 5分間 です。再試行しても有効期間は延長されません。
- 保留中の確認ごとに再試行は 1回 です。有効期間内に同じ番号へ2回目の送信を行うと、同じ
request_idを含む"Retry"が返されます（合計2回送信）。さらに送信すると、新しいrequest_idで新たな確認が開始されます。 - 確認ごとのコード試行回数は 3回 です。1回目と2回目に誤ったコードを入力すると
"Failed"が返され、3回目に誤ったコードを入力すると確認が確定され、"Declined"（VERIFICATION_CODE_ATTEMPTS_EXCEEDED）になります。 codeは 4～8桁 である必要があります（^[0-9]{4,8}$）。それ以外の場合は、試行回数を消費せずに400が返されます。- 不正利用対策の上限：電話番号ごとに1時間あたり4回の送信試行（
429）。 - 保留中の確認がない場合（未送信、確定済み、送信時にブロック、または送信から5分超過）、確認には
status: "Expired or Not Found"を含む HTTP200が返されます。 - 電話番号確認は、組織で初回の入金が行われるまで 無効 です（
403）。 - 新しい確認はそれぞれ API セッションとして保存されます。
request_idはGET /v3/session/{sessionId}/decision/で使用でき、Business Console に表示され、進行に応じてstatus.updatedWebhook が発火します。
配信チャネル： options.preferred_channel は whatsapp（デフォルト）、sms、telegram、voice、rcs、viber、zalo のいずれかです（利用可否は国によって異なります）。電話番号で優先チャネルを利用できない場合、配信は SMS にフォールバックしますが、送信の応答は "Success" のままです。配信に使用されたチャネルは phone.verification_method と、phone.lifecycle の送信イベント（details.actual_channel）に記録されます。
ブランディング： SMS コードには追加料金なしで、お客様のアプリケーションの SMS 送信者名（Business Console で設定）を表示できます。options.sms_sender_name を指定すると、コード1件に別の名前を付けられます。送信者名が設定されていない場合、options.use_white_label_customization: true を指定すると、ホワイトラベルの公開名が使用されます。WhatsApp コードのメッセージは固定されており、ブランディングには対応していません。
機能： 通信事業者名と回線種別、VoIP／仮想番号および使い捨て番号、お客様のセッション間の重複（matches[]）、電話番号のブロックリスト／許可リスト、送信時の不正対策ブロック、任意のソーシャルフットプリント（enable_social）、不正利用シグナル。
サンドボックス： サンドボックス API キーでは、配信、課金、永続化がスキップされます。送信ではランダムな request_id を含む固定の "Success" が返されます。確認にはコード 123456 を使用してください（形式が正しいコードであれば、フラットな phone オブジェクトを含む簡易版の "Approved" ペイロードが返されます）。リスクでは決定的な承認データが返されます。形式が不正な入力には引き続き 400 が返されます。
料金： Phone Verification は、送信メッセージ1件につき $0.04 と通信事業者手数料がかかります。料金は宛先の国と実際に配信されたチャネルによって異なります（料金表）。"Blocked" を除くすべての送信が課金対象で、"Retry" も含まれます。確認は無料です（任意のソーシャル機能の追加料金を除く）。単独の呼び出しには無料枠がありません。POST /v3/phone/risk/ の公開価格は掲載されていません（ドキュメントでは Phone Verification より安価とされています）。ソーシャルフットプリントの追加機能（enable_social）の公開価格も掲載されていません（エンドポイント料金に加えてリクエストごとに課金され、照会を完了できなかった場合は課金されません）。これらは2026年11月1日までの公開価格です。同日以降、Didit の料金体系が変更され、月500件の無料確認は月額 $10 分の無料クレジットになります。最新の料金は didit.me/pricing をご確認ください。
API リファレンス： コードの送信 | コードの確認 | 電話番号リスク
機能ガイド： https://docs.didit.me/core-technology/phone-verification/overview
認証
すべてのリクエストに x-api-key ヘッダーが必要です。Didit Business Console の Developers > API keys にあるアプリケーションの API キーを使用するか、アカウントとキーをプログラムから作成してください（「はじめに」を参照）。アクセス権をカスタマイズした名前付きキーで単独チェックを実行するには、Sessions の書き込み権限が必要です。一部のワークフローに限定されたキーや、承認済みセッションに限定されたキーでは実行できません。
はじめに（アカウントをお持ちでない場合）
Didit API キーをお持ちでない場合は、2 回の API 呼び出しで作成できます。
- 登録：
POST https://apx.didit.me/auth/v2/programmatic/register/に{"email": "[email protected]", "password": "MyStr0ng!Pass"}を送信します。 - メールを確認し、6 文字の認証コードを取得します。
- 認証：
POST https://apx.didit.me/auth/v2/programmatic/verify-email/に{"email": "[email protected]", "code": "A3K9F2"}を送信します。キーはレスポンスのapplication.api_keyに含まれています。
クレジットの追加： GET /v3/billing/balance/ で残高を確認し、POST /v3/billing/top-up/ に {"amount_in_dollars": 50} を送信すると、Stripe のチェックアウトリンクを取得できます。
プラットフォーム管理（ワークフロー、セッション、ユーザー、請求）の詳細については、didit-verification-management スキルを参照してください。
ステップ 1：電話番号にコードを送信
POST https://verification.didit.me/v3/phone/send/
ヘッダー
| ヘッダー | 値 | 必須 |
|---|---|---|
x-api-key | API キー | はい |
Content-Type | application/json | はい |
本文（JSON）
| パラメーター | 型 | 必須 | デフォルト | 制約 | 説明 |
|---|---|---|---|---|---|
phone_number | 文字列 | はい | - | E.164、最大 20 文字 | 電話番号（例：+14155552671） |
options.code_size | 整数 | いいえ | 6 | 4～8 | 桁数 |
options.locale | 文字列 | いいえ | - | 最大 5 文字、BCP-47（^[a-z]{2,3}(-[A-Z]{2,3})?$） | メッセージの言語。例：en-US、fr、es |
options.preferred_channel | 文字列 | いいえ | "whatsapp" | whatsapp、sms、telegram、voice、rcs、viber、zalo | 優先するチャネル。利用できない場合は SMS にフォールバックします |
options.sms_sender_name | 文字列または null | いいえ | アプリの SMS 送信者名 | 1～30 文字：英字、数字、スペース、' & - !。数字のみは不可。スペースは連続不可 | このコードを SMS で送信する際に表示する名前（「123456 is your verification code for Example Bank」）。無効な値の場合は 400 を返し、コードは送信されません。各アプリケーションで 1 日（UTC）に使用を開始できる新しい名前は最大 2 つです。それを超えると、アプリの名前が使用されます。無料 |
options.use_white_label_customization | ブール値 | いいえ | false | - | SMS 送信者名が指定されていない場合、ホワイトラベルの公開名を SMS に表示します |
signals.ip | 文字列 | いいえ | - | IPv4 または IPv6 | 不正検出に使用するエンドユーザーの IP アドレス |
signals.device_id | 文字列 | いいえ | - | 最大 255 文字 | Android の ANDROID_ID、iOS の identifierForVendor |
signals.device_platform | 文字列 | いいえ | - | android、ios、ipados、tvos、web | デバイスのプラットフォーム |
signals.device_model | 文字列 | いいえ | - | 最大 255 文字 | 例：iPhone17,2 |
signals.os_version | 文字列 | いいえ | - | 最大 64 文字 | 例：18.0.1 |
signals.app_version | 文字列 | いいえ | - | 最大 64 文字 | 例：1.2.34 |
signals.user_agent | 文字列 | いいえ | - | 最大 512 文字 | ブラウザーまたはアプリのユーザーエージェント |
vendor_data | 文字列 | いいえ | - | - | ユーザー ID。セッションに保存され（初回送信時）、送信、確認、Webhook で返されます |
metadata | オブジェクト | いいえ | null | JSON オブジェクト | セッションに保存され、応答で返される任意のデータ |
例
import requests
response = requests.post(
"https://verification.didit.me/v3/phone/send/",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={
"phone_number": "+14155552671",
"options": {"preferred_channel": "sms", "code_size": 6, "sms_sender_name": "Example Bank"},
"signals": {"ip": "203.0.113.42", "device_platform": "ios"},
"vendor_data": "user-1234",
},
timeout=30,
)
print(response.status_code, response.json())
const response = await fetch("https://verification.didit.me/v3/phone/send/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
phone_number: "+14155552671",
options: { preferred_channel: "whatsapp", code_size: 6, locale: "en-US" },
vendor_data: "user-1234",
}),
});
const data = await response.json(); // { request_id, status, reason, vendor_data, metadata }
レスポンス（200 OK）
{
"request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
"status": "Success",
"reason": null,
"vendor_data": "user-1234",
"metadata": null
}
ステータス値とその処理
| ステータス | 意味 | 操作 |
|---|---|---|
"Success" | 新しい認証のためにコードが送信されました（SMS のフォールバック経由の場合があります） | ユーザーがコードを受け取るまで待ってから、Check を呼び出します |
"Retry" | 5 分間のウィンドウ内で 2 回目の送信が行われました。同じ保留中の認証に対して、同じ request_id でコードが再送されました（課金対象） | コードを受け取るまで待ってから、Check を呼び出します |
"Blocked" | 不正対策レイヤーによって送信が拒否されました。reason に理由（例：suspicious、spam）が示されます。課金されません。認証はすぐに確定し（HIGH_RISK_PHONE_NUMBER を伴う Declined、または許可リストに登録された番号の場合は In Review）、後続のチェックでは "Expired or Not Found" が返されます | 同じ番号で再試行しないでください。別の番号を尋ねるか、確認してください |
エラーレスポンス
| コード | 意味 | 操作 |
|---|---|---|
400 | リクエストが無効です | レスポンス本文のフィールドエラーを確認してください。解析できてもコードを受信できない番号の場合は、{"detail": "Invalid phone number provided."} または {"detail": "Invalid phone line type provided."}（例：ショートコード）が返されます |
401 | API キーの有効期限が切れています | Developers > API keys でキーをローテーションするか、新しいキーを作成してください |
403 | API キーがない、誤っている、または取り消されている場合、このエンドポイントへのアクセス権がないスコープ付きキーを使用している場合、キーの IP 許可リスト外からリクエストしている場合、またはクレジットが不足している場合 | detail または error のメッセージを確認してください。x-api-key ヘッダーまたはキーのアクセス権を修正するか、残高を追加してください |
429 | レート制限：キーごとに 1 分あたり POST/PATCH/DELETE リクエストは 300 件、GET リクエストは 600 件 | Retry-After 秒待ってから再試行してください |
502 | 電話プロバイダーが一時的に利用できません：{"detail": "...", "code": "phone_provider_unavailable"} | 短いバックオフを挟んで再試行してください。課金されず、試行回数も消費されません |
電話固有のケース：組織の初回チャージが完了するまで電話認証が無効であることを示す detail を伴う 403（サンドボックスアプリケーションでは引き続き無料でテストできます）、および残高が送信先への送信料金に満たない場合の error を伴う 403。同じ番号への試行回数が多すぎる場合（1 時間に 4 回）の 429 には Retry-After ヘッダーがありません。時間をおくか、別の番号を使用してください。
ステップ 2：電話コードを確認する
コードを検証し、電話レポートを返します。最初に、同じ phone_number を指定して Send を呼び出してください。
POST https://verification.didit.me/v3/phone/check/
ヘッダー：ステップ 1 と同じです。
本文（JSON）
| パラメーター | 型 | 必須 | デフォルト | 値 | 説明 |
|---|---|---|---|---|---|
phone_number | string | はい | - | E.164 | ステップ 1 で使用した番号（これにより確認が送信リクエストに関連付けられます） |
code | string | はい | - | 4～8 桁 | ユーザーが受け取ったコード |
duplicated_phone_number_action | string | いいえ | "NO_ACTION" | "NO_ACTION" / "DECLINE" | アプリケーションの別のユーザー（異なる vendor_data）がすでに使用している番号 |
disposable_number_action | string | いいえ | "NO_ACTION" | "NO_ACTION" / "DECLINE" | 一時的な番号または使い捨て番号（phone.is_disposable） |
voip_number_action | string | いいえ | "NO_ACTION" | "NO_ACTION" / "DECLINE" | 仮想回線：voip、isp、または vpn（phone.is_virtual） |
enable_social | boolean | いいえ | false | - | 番号のソーシャルフットプリントも検索します（phone.phone_social が追加され、リクエストごとにアドオンとして課金されます） |
phone_no_social_presence_action | string | いいえ | "NO_ACTION" | "NO_ACTION" / "DECLINE" | ソーシャルフットプリントの確認で、どのプラットフォームにも番号が見つからなかった場合（profiles_registered: 0）に拒否します。enable_social: true が必要です |
ポリシーに関する注意： リスクが見つかった場合、
DECLINEは正しいコードでもステータスを"Declined"にします。NO_ACTIONはステータスを変更せず、リスクをphone.warnings（ログタイプinformation）に記録します。ブロックリストに登録された番号は常に拒否されます。ここで受け付けられるのはNO_ACTIONとDECLINEのみです。
例
response = requests.post(
"https://verification.didit.me/v3/phone/check/",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={
"phone_number": "+14155552671",
"code": "123456",
"disposable_number_action": "DECLINE",
"voip_number_action": "DECLINE",
},
timeout=30,
)
result = response.json()
if result["status"] in ("Approved", "Declined"):
print(result["phone"]["carrier"], result["phone"]["is_virtual"])
const response = await fetch("https://verification.didit.me/v3/phone/check/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
phone_number: "+14155552671",
code: "123456",
voip_number_action: "DECLINE",
}),
});
const result = await response.json(); // inspect result.status, not the HTTP code
レスポンス（200 OK）
{
"request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
"status": "Approved",
"message": "The verification code is correct.",
"phone": {
"status": "Approved",
"phone_number_prefix": "+1",
"phone_number": "4155552671",
"full_number": "+14155552671",
"country_code": "US",
"country_name": "United States",
"carrier": {"name": "Example Mobile", "type": "mobile"},
"is_disposable": false,
"is_virtual": false,
"verification_method": "whatsapp",
"verification_attempts": 1,
"verified_at": "2026-06-12T01:24:47.311323Z",
"warnings": [],
"lifecycle": [
{"type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": {"status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp"}, "fee": 0.0709},
{"type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-06-12T01:23:43.118220+00:00", "details": {"channel": "whatsapp", "status": "delivered"}, "fee": 0},
{"type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": {"code_tried": "123456", "status": "Approved"}, "fee": 0},
{"type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0}
],
"matches": []
},
"vendor_data": "user-1234",
"metadata": null,
"created_at": "2026-06-12T01:24:47.401719+00:00"
}
試行回数が残っている状態で誤ったコードを入力すると、"status": "Failed"、"message": "The verification code is incorrect. Attempts remaining: 2"、および "phone": null が返されます。
ステータス値と処理
| ステータス | 意味 | request_id / phone | アクション |
|---|---|---|---|
"Approved" | コードが正しく、拒否リスクはありません | 送信のセッション ID / 完全なレポート | 電話番号の確認が完了しました。次に進みます |
"Declined" | 終了状態：コードは正しいものの、拒否リスクに該当した（DECLINE アクション、ブロックリスト登録済み、または高リスクの番号）、または3回目のコード入力ミスです | 送信のセッション ID / 完全なレポート | phone.warnings を確認し、ブロックするか別の番号を尋ねます |
"Failed" | コードが間違っています。試行回数が残っています（message に残りの回数が記載されています） | 1回限りの UUID / null | ユーザーにコードを再入力するよう求めます |
"Expired or Not Found" | 過去5分間、この番号に対する保留中の確認がありません | 1回限りの UUID / なし | 新しいコードを送信します（ステップ1） |
エラーレスポンス
| コード | 意味 | アクション |
|---|---|---|
400 | リクエストが無効です | レスポンス本文のフィールドエラーを確認します（コードが4～8桁でない、番号が無効、アクションが NO_ACTION / DECLINE ではない）。試行回数は消費されません |
401 | API キーの有効期限が切れています | Developers > API keys でキーをローテーションするか、新しいキーを作成します |
403 | API キーがない、間違っている、または取り消されている、このエンドポイントへのアクセス権がないスコープ付きキーを使用している、キーの IP 許可リスト外からのリクエストである、またはクレジットが不足しています | detail または error のメッセージを確認し、x-api-key ヘッダーまたはキーのアクセス権を修正するか、残高を補充します |
429 | レート制限：キーごとに1分あたり POST/PATCH/DELETE は300件、GET は600件です | Retry-After 秒待ってから再試行します |
502 | 電話プロバイダーが一時的に利用できません（"code": "phone_provider_unavailable"） | 短いバックオフを入れて再試行します。試行回数は消費されません |
チェックは無料です。クレジット確認が行われるのは enable_social アドオンのみです（残高で費用をまかなえない場合は error を伴う 403 が返されます）。
電話番号リスク（コードは送信されません）
1回の同期呼び出しで、通信事業者、回線種別、番号ポータビリティ、使い捨て番号、重複、正規化されたリスク情報をスコアリングします。コードは送信されず、ユーザーの操作も不要です。API セッション（request_id）が作成されます。
POST https://verification.didit.me/v3/phone/risk/
本文（JSON）
| パラメーター | 型 | 必須 | デフォルト | 説明 |
|---|---|---|---|---|
phone_number | string | はい | - | スコアリングする番号（最大20文字、E.164 に正規化されます） |
country_code | string | いいえ | - | ISO 3166-1 alpha-2 または alpha-3 の国コードヒント（最大3文字） |
signals | object | いいえ | - | ステップ1の signals と同じフィールドです |
enable_social | boolean | いいえ | false | phone.phone_social ブロックを追加します（アドオンとしてリクエストごとに課金されます） |
vendor_data | string | いいえ | - | 参照情報です。保存され、レスポンスに含まれます |
metadata | object | いいえ | null | JSON メタデータです。保存され、レスポンスに含まれます |
例
response = requests.post(
"https://verification.didit.me/v3/phone/risk/",
headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
json={"phone_number": "+14155552671", "country_code": "US", "vendor_data": "lead-123"},
timeout=30,
)
result = response.json()
print(result["status"], result["phone"]["is_virtual"], result["phone"].get("phone_intelligence"))
const response = await fetch("https://verification.didit.me/v3/phone/risk/", {
method: "POST",
headers: { "x-api-key": "YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({ phone_number: "+14155552671", country_code: "US", vendor_data: "lead-123" }),
});
const result = await response.json();
レスポンス（200 OK）
{
"request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62",
"status": "Approved",
"phone": {
"status": "Approved",
"phone_number_prefix": "+1",
"phone_number": "4155552671",
"full_number": "+14155552671",
"country_code": "US",
"country_name": "United States",
"carrier": {"name": "Example Mobile", "type": "mobile"},
"is_disposable": false,
"is_virtual": false,
"verification_method": null,
"verification_attempts": 0,
"verified_at": null,
"warnings": [],
"lifecycle": [],
"matches": [],
"phone_intelligence": {
"score": 3.0,
"phone_type_risk": "Low",
"phone_trust_index": 97,
"network_stability_index": 95,
"is_disposable": false,
"is_ported": false,
"is_recently_ported": false,
"carrier_type": "mobile",
"reason_codes": []
},
"enrichment": {
"score": 3.0,
"phone_type_risk": "Low",
"phone_trust_index": 97,
"network_stability_index": 95,
"is_disposable": false,
"is_ported": false,
"is_recently_ported": false,
"carrier_type": "mobile",
"reason_codes": []
}
},
"vendor_data": "lead-123",
"metadata": null,
"created_at": "2026-09-01T10:30:00.123456+00:00"
}
status（トップレベルおよびphone.status）："Approved"、"In Review"、または"Declined"です。通常は"Approved"ですが、アプリケーションの電話番号リスクルールによっては、ほかのステータスになることがあります。ルックアップが完了すると、すべて HTTP200が返されます。phone.phone_intelligenceとphone.enrichmentは同じオブジェクトです（互換性のためのエイリアス）。これらはベストエフォートで提供されます。有効な情報を取得できなかった場合、両方のキーが省略されます。まずis_disposableとis_virtualに基づいてルールを設定し、ブロックがない場合は「安全」ではなく「不明」として扱ってください。通信事業者が特定できなかった場合、phone.carrierはnullになることがあります。- ベストエフォートのフィールドが欠落していても、ルックアップの開始時に課金されます。
エラー：ステップ2と同様に、400（フィールドエラー）、401、403（呼び出しおよび enable_social アドオンのクレジット確認を含む）、429 が返されます。
レスポンスフィールドのリファレンス
phone オブジェクト（チェックとリスク）
| フィールド | 型 | 説明 |
|---|---|---|
status | string | チェック：最終確定したチェックでは "Approved" または "Declined"（列挙型には "In Review"、"Not Finished"、"Expired" も含まれます）。リスク："Approved"、"In Review"、"Declined" |
phone_number_prefix | string | + 付きの国番号（例：+1） |
phone_number | string | 国番号を除いた国内の電話番号 |
full_number | string | E.164 形式の完全な電話番号 |
country_code / country_name | string | 電話番号の ISO 3166-1 alpha-2 国コードと国名 |
carrier.name | string | 通信事業者名（不明な場合は空文字列） |
carrier.type | string | mobile、fixed_line、voip、isp、vpn、toll_free、premium_rate、pager、payphone、satellite、service、shared_cost、short_codes_commercial、calling_cards、local_rate、universal_access、voice_mail、other、unknown |
is_disposable | boolean | 一時利用または使い捨て電話番号サービス |
is_virtual | boolean | 回線タイプが voip、isp、または vpn |
verification_method | string | 配信が確認された場合はコードを配信したチャネル、それ以外の場合は要求されたチャネル。リスク照会では null |
verification_attempts | integer | この検証でコードを送信した回数（1、再試行後は2）。リスク照会では 0 |
verified_at | string or null | 正しいコードが入力された日時 |
warnings | array | {feature, risk, additional_data, log_type, short_description, long_description}。log_type：error は却下、warning は審査対象としてフラグ付け、information は記録のみ |
lifecycle | array | {type, timestamp, details, fee}。タイプ：PHONE_VERIFICATION_MESSAGE_SENT、PHONE_VERIFICATION_RETRY_MESSAGE_SENT、PHONE_VERIFICATION_BLOCKED、PHONE_DELIVERY_DELIVERED、PHONE_DELIVERY_UNDELIVERABLE、VALID_CODE_ENTERED、INVALID_CODE_ENTERED、PHONE_VERIFICATION_APPROVED、PHONE_VERIFICATION_DECLINED、PHONE_VERIFICATION_IN_REVIEW、PHONE_VERIFICATION_EXPIRED。送信イベントには {status, reason, channel, actual_channel} が含まれます。fee（USD）がゼロ以外になるのは送信イベントのみです |
matches | array | 異なるユーザー（vendor_data）がこの番号を使用した、アプリケーション内の他のセッション（最大5件）：{session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source}。source は session、またはブロックリストエントリーの場合は list_entry です |
phone_intelligence / enrichment | object | リスクエンドポイントのみ。ベストエフォート：score（0～100、高いほどリスクが高い）、phone_type_risk（Low/Medium/High）、phone_trust_index（スコアの逆指標）、network_stability_index、is_disposable、is_ported、is_recently_ported、carrier_type、reason_codes（追加される可能性があるため、未知のコードを理由に却下しないでください） |
phone_social | object | enable_social: true かつ照会完了時のみ：profiles_registered / profiles_checked（登録数 0 は実際の課金対象となる回答です）、件数、0～10 の指数、whatsapp_profile_completeness（Basic、Partial、Complete、Not Present）、registered_platforms、not_registered_platforms、categories、profiles。件数が null になる場合があります |
警告タグ
| タグ | 重大度 | 説明 |
|---|---|---|
VERIFICATION_CODE_ATTEMPTS_EXCEEDED | error（常に拒否） | 単独チェックで3回目に間違ったコードを入力した場合 |
PHONE_NUMBER_IN_BLOCKLIST | error（常に拒否） | 電話番号のブロックリスト（Lists API）に登録されている番号、またはブロックリストに登録されたセッションと一致した番号です。additional_data：blocklisted_session_id、blocklisted_session_number、api_service |
HIGH_RISK_PHONE_NUMBER | デフォルトでは error | 不正対策レイヤーによって送信時にブロックされた場合（"Blocked"）に発生し、拒否されます。電話番号の許可リストに登録されている番号の場合は、代わりに In Review になります（log_type: "warning"、additional_data.phone_number_in_allowlist: true）。additional_data.blocked_reason には送信時の reason が格納されます |
DISPOSABLE_NUMBER_DETECTED | disposable_number_action による | 一時的な番号、または使い捨て番号です |
VOIP_NUMBER_DETECTED | voip_number_action による | 回線種別が voip、isp、または vpn です |
DUPLICATED_PHONE_NUMBER | duplicated_phone_number_action による | 別のセッション（ステータスは問いません）で別のユーザーが使用している番号です。additional_data：duplicated_session_id、duplicated_session_number、api_service |
PHONE_NUMBER_IN_ALLOWLIST | information | 他のセッションと一致しましたが、電話番号の許可リストに登録されているため、重複時のアクションはスキップされました。additional_data：phone_number |
この API では、DECLINE アクションのログタイプは error、NO_ACTION のログタイプは information です。
一般的なワークフロー
基本的な電話番号認証
1. POST /v3/phone/send/ -> {"phone_number": "+14155552671"}
If "Blocked" -> ask for another number (nothing billed)
2. Wait for the user to type the code (valid 5 minutes from the first send)
3. POST /v3/phone/check/ -> {"phone_number": "+14155552671", "code": "123456"}
4. If "Approved" -> phone verified
If "Failed" -> ask the user to retry (3 attempts in total)
If "Declined" -> read phone.warnings
If "Expired or Not Found" -> send again (step 1)
厳格なセキュリティ認証
1. POST /v3/phone/send/ -> include signals.ip, signals.device_platform, vendor_data,
options.preferred_channel: "sms"
2. POST /v3/phone/check/ -> disposable_number_action, voip_number_action,
duplicated_phone_number_action = "DECLINE"
3. If "Declined" -> phone.warnings[].risk says why; block or ask for another number
コードを使わない事前スクリーニング
1. POST /v3/phone/risk/ -> {"phone_number": "+14155552671", "vendor_data": "lead-123"}
2. If phone.is_virtual or phone.is_disposable -> reject before sending any OTP
3. Otherwise continue with the send/check flow above
ユーティリティスクリプト
verify_phone.py：コマンドラインからコードの送信と確認、および電話番号のリスク評価を行います。
# Requires: pip install requests
export DIDIT_API_KEY="your_api_key"
python scripts/verify_phone.py send +14155552671 --channel sms --sms-sender-name "Example Bank"
python scripts/verify_phone.py check +14155552671 123456 --decline-voip --decline-disposable
python scripts/verify_phone.py risk +14155552671 --country-code US
ライブラリとしてインポートすることもできます：
from scripts.verify_phone import send_code, check_code, score_phone_risk
send_result = send_code("+14155552671", channel="sms")
check_result = check_code("+14155552671", "123456", decline_voip=True)
risk_result = score_phone_risk("+14155552671")
コメント
Markdown 対応