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

# 電話番号認証API - SMS・WhatsAppのOTP

> DiditはSMS、WhatsApp、Telegram、RCS、音声のOTPで電話番号を認証します。キャリア判定とリスク評価に対応し、料金は1回$0.02にキャリア料金を加えた従量課金です。

Diditの電話番号認証は、ワンタイムパスコード(OTP)でユーザーの電話番号を確認する信頼性の高い方法です。本人確認プロセスにセキュリティの層を加え、正当な連絡先情報であることを確実にします。

電話番号認証の連携プロンプト
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Phone Verification (OTP send + check + carrier/risk lookup) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow — the SDK collects the number and OTP for you.

1\. Add the PHONE feature to the workflow (Business Console or POST /v3/workflows/). Configure risk actions: duplicated_phone_number_action, disposable_number_action, voip_number_action.
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `phone_verifications[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server, OTP pair)
Two endpoints, paired by phone_number.

Step 1 — send the code:
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/send/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"options": {
  "code_size": 6,
  "preferred_channel": "whatsapp",
  "locale": "en-US"
},
"vendor_data": "user-1234"
}'
\```
Channels: `whatsapp` (default), `sms`, `telegram`, `voice` — delivery falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.
Branding: SMS codes carry your app's SMS sender name ("123456 is your verification code for Acme Bank") on every send, at no extra cost; set it in the Business Console. Pass `options.sms_sender_name` to sign one code with another name (1 to 30 characters). WhatsApp codes use a fixed message; connect your own WhatsApp Business number in the Business Console to send them under your business name.

Step 2 — check the code (user types it into your UI):
\```bash
curl -X POST 'https://verification.didit.me/v3/phone/check/' \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155552671",
"code": "123456",
"voip_number_action": "DECLINE"
}'
\```
Each session accepts **up to 3** code-entry attempts. The check response includes the full phone metadata (carrier, line_type, disposable, voip, ported).

\# Status enum (per phone_verifications[].status / phone.status)
"Not Started" | "In Progress" | "Approved" | "Declined" | "Failed" | "Expired or Not Found" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.PHONE)
warnings[] risk codes include:
DUPLICATED_PHONE_NUMBER, DISPOSABLE_NUMBER, VOIP_NUMBER, INVALID_PHONE_NUMBER, OTP_DELIVERY_FAILED, OTP_MAX_ATTEMPTS_REACHED, OTP_EXPIRED, PHONE_NUMBER_BLOCKED.
Full catalogue: /core-technology/phone-verification/warnings-phone-verification.

\# Failure modes to handle
\- HTTP 400 — non-E.164 phone_number on /send/.
\- send response status="Blocked" with reason="spam" — anti-abuse block; no code sent, no charge.
\- check response status="Failed" — wrong code, attempts remaining; re-prompt.
\- check response status="Declined" — third failed attempt; restart with /v3/phone/send/.
\- check response status="Expired or Not Found" — outside the 5-minute window or no pending session for that number; restart.

\# See also
\- Canonical schema: /reference/data-models#phone-verification
\- Per-feature report: /core-technology/phone-verification/report-phone-verification
\- Risk catalogue: /core-technology/phone-verification/warnings-phone-verification
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

Academyの「検証結果の読み方」のレッスンでは、8:08のチャプターで電話番号認証と重複検知を取り上げています。[電話番号認証と重複検知 — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=488\&rel=0\&playsinline=1)![電話番号認証フローの図](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/phone-verification-flow.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=6c12863ce97e5ad6a11757b598918932)## 仕組みDiditの電話番号認証は、シンプルでユーザーに優しいプロセスで、包括的な電話番号の検証を実現します。OTP認証と高度なリスク評価を組み合わせ、大規模でも信頼できる電話番号認証を提供します。**1. 電話番号の収集**システムは次の情報を安全に収集します。| 収集するデータ | 詳細 |
| - | - |
| **電話番号** | セッション作成時に指定されていない場合、ユーザーが国際形式で電話番号を入力します。指定されている場合は、ユーザーが入力済みの番号を確認する必要があります。 |
| **国コード** | IPの位置情報またはユーザーの選択に基づいて自動で提案されます。 |
| **キャリアの種類** | 携帯電話番号か固定電話番号かを判定します。 |**2. OTPの生成と配信**Diditの認証システムは次を行います。- 安全で有効期限のあるワンタイムパスコードを生成する
- 指定された番号にSMSでコードを配信する
- 複数のキャリアとの連携により、配信を最適化する
- 配信に問題があった場合のフォールバックを提供する**3. コードの検証**ユーザーは次の操作で認証を完了します。- 受け取ったコードを認証画面に入力する
- 設定された時間内(通常は5〜10分)に送信する
- 必要に応じて新しいコードを要求する(適切なレート制限あり)**4. リスク評価**システムは高度なチェックを実行します。| チェック | 説明 |
| - | - |
| **形式とキャリア** | 電話番号の形式とキャリア情報を検証します。 |
| **使い捨て番号** | 既知の使い捨て・仮想番号のデータベースと照合します。 |
| **SIMスワップ検知** | SIMスワップの潜在的なリスクを特定します。 |
| **アクティビティパターン** | 不審なアクティビティパターンを検知します。 |
| **過去のデータ** | 過去の認証データと照合します。 |**5. 結果の提供**認証結果は複数のチャネルで確認できます。| チャネル | 説明 |
| - | - |
| **ダッシュボード** | リアルタイムで更新されるダッシュボード。 |
| **Webhook** | 即時のWebhook通知。 |
| **API** | RESTful APIによる連携。 |
| **レポート** | 認証の詳細情報を含む包括的なレポート。 |## 認証機能Diditの電話番号認証サービスには、認証プロセスを強化するいくつかの主要な機能があります。#### OTP認証- **安全なコード生成**: ランダムに生成されるワンタイムパスコード
- **SMS配信**: モバイル端末への高速で信頼性の高い配信
- **有効期限の設定**: セキュリティ要件に応じて有効期限を設定できます
- **再送オプション**: 適切なレート制限のもとで、ユーザーが新しいコードを要求できます
- **ブランド名入りのコード**: SMSコードに汎用的なメッセージではなくブランド名を記載できます。追加料金はかかりません。[ブランド名入りの認証メッセージ](#ブランド名入りの認証メッセージ)をご覧ください。
- **自社のWhatsApp番号**: WhatsAppのコードを、自社のWhatsApp Business番号から送信できます。[自社の番号からWhatsAppコードを送信する](#自社の番号からwhatsappコードを送信する)をご覧ください。#### ブランド名入りの認証メッセージSMSの認証コードにブランド名を記載できるため、ユーザーは自社からのメッセージだと認識できます。> 123456 は **Acme Bank** の認証コードですカスタマイズできるのは名前のみです。
それ以外の文面は、各国の携帯電話会社に登録された標準の文面で、コードがスパムとしてフィルタリングされるのを防ぎ、受信者の言語に翻訳されます。
ブランド名の設定は無料です。ブランド名入りのコードも、ブランド名なしのコードと料金は同じです。**SMSの送信者名を設定する**には、ビジネスコンソールで、ワークフローの**電話番号認証 → 設定**、または**ホワイトラベル → SMS**を開きます。
送信者名は、1つのワークフローではなくアプリケーションに紐付きます。ホワイトラベルのカスタマイズの有無にかかわらず、アプリケーションが送信するすべてのSMSコードに、すべてのワークフローとスタンドアロンAPIで署名されます。**コードに記載される名前**は、上から順に最初に該当したものが使われます。1) [`POST /v3/phone/send/`](https://docs.didit.me/standalone-apis/phone-send)の`options.sms_sender_name`(そのコード1件のみ)。
2) アプリケーションのSMS送信者名。
3) ホワイトラベルでの送信のみ(ホワイトラベルのカスタマイズを設定したワークフロー、またはAPIで`options.use_white_label_customization: true`を指定した場合)、ホワイトラベルの公開名。
4) いずれもない場合、名前なしでコードを送信します。送信者名は1〜30文字で、使用できるのは英字、数字、スペース、および ' & - ! のみです。数字のみの名前は使用できず、単語の間のスペースは1つにします。
これらのルールに合わない名前は、コードが送信される前にAPIが`400`で拒否します。- **チャネル**: 名前はSMSメッセージに追加されます。他のチャネルからのフォールバックとして送信されるSMSも含まれます。WhatsAppのコードは固定のメッセージで送信され、名前は付きません。ビジネス名を表示するには、[自社の番号から送信](#自社の番号からwhatsappコードを送信する)してください。
- **1日あたりの変更回数**: 各アプリケーションが1日(UTC)に使い始められる新しい名前は最大2つで、新しい送信者名と新しい`sms_sender_name`の値の両方が対象です。それを超えると、翌日までコードにはアプリケーションの現在の名前が使われ、リクエストごとの新しい名前は、アプリケーションの名前とともに送信されます。以前に使用した名前は再カウントされません。
- **配信を最優先**: ブランド名の問題でコードの送信が止まることはありません。名前を適用できない場合は、アプリケーションの名前、または名前なしでコードが送信されます。#### 自社の番号からWhatsAppコードを送信するデフォルトでは、WhatsAppのコードはDiditのWhatsApp Business番号から送信されます。
代わりに自社のWhatsApp Business番号を接続すると、ユーザーは自社のビジネス名と番号からコードを受け取れます。**番号を接続する**には、ビジネスコンソールで、ワークフローの**電話番号認証 → 設定 → WhatsApp 番号**を開き、**WhatsApp 番号を接続**を選択します。
サインインウィンドウが開きます。WhatsApp Business番号を管理しているビジネスアカウントにサインインし、送信元のWhatsApp Businessアカウントと番号を選択してください。
その後、Diditが送信用に番号を登録し、認証メッセージを作成します。
編集にはカスタマイズの編集権限が必要で、SMSの送信者名と同じです。番号は、1つのワークフローではなくアプリケーションに紐付きます。接続すると、アプリケーションが送信するすべてのWhatsAppコードが、すべてのワークフローとスタンドアロンAPIで、その番号から送信されます。- **承認**: 番号がコードを送信できるようになるには、新しい認証メッセージの承認が必要です。通常は数分で完了します。それまでカードには、番号が承認待ちであることが表示され、その間もコードはDiditの番号から送信され続けます。
- **メッセージの文面**: WhatsAppの認証メッセージは、ユーザーの言語の標準の文面で、コード、セキュリティに関する注意書き、コピーボタンで構成されます。文面は編集できませんが、送信元はお客様のビジネスになります。
- **配信**: WhatsAppでコードを配信できない場合は、SMSで送信され、SMSの送信者名が署名されます。
- **課金**: 番号から送信されたメッセージはWhatsApp Businessアカウントに請求されるため、それらのコードについてDiditが請求するのは認証手数料(\$0.02)のみです。SMSで送信されたコードは通常どおり課金されます。
- **要対応**: 番号が送信できなくなった場合(たとえば、ビジネスアカウントからアクセスが削除された場合)は、再びDiditの番号からコードが送信され、カードに番号の再接続を求める表示が出ます。
- **接続解除**は、同じカードからいつでも行えます。コードは再びDiditの番号から送信されます。番号とその認証メッセージは、WhatsApp Businessアカウントに残ります。#### 電話番号の分析- **形式の検証**: 電話番号が正しい国際形式であることを確認します
- **キャリア判定**: 番号に紐付く通信事業者を特定します
- **番号の種類**: 携帯電話、固定電話、VoIPの番号を区別します
- **国の検証**: 電話番号が想定される国の形式と一致していることを確認します#### リスク評価- **使い捨て番号の検知**: 追跡を避けるために使われる一時的な番号を特定します
- **仮想番号の識別**: 仮想番号やVoIPベースの可能性がある番号にフラグを付けます
- **アクティビティの監視**: 認証の試行をまたぐ不審なパターンを追跡します
- **ブロックリストの確認**: 過去に不正利用された番号の社内リストと照合します## 料金電話番号認証は、**送信したメッセージごと**に課金される、わかりやすい従量課金制です。| 項目 | 費用 |
| - | - |
| **Diditの手数料** | 認証1回あたり\$0.02 |
| **キャリア料金** | 国とチャネルによって異なります |
| **合計** | \$0.02 + キャリア料金 |プランの割引が適用されるのはDiditの手数料\$0.02のみです。キャリア料金は原価のまま請求され、割引されることはありません。[割引](https://docs.didit.me/getting-started/pricing.md#discounts)をご覧ください。複数の配信チャネルに対応しており、チャネルごとに料金が異なります(提供状況は国によって異なります)。| チャネル | 説明 |
| - | - |
| **SMS** | 従来のテキストメッセージによる配信 |
| **WhatsApp** | WhatsAppメッセージによる配信 |
| **Telegram** | Telegramメッセージによる配信 |
| **RCS** | リッチコミュニケーションサービス(RCS)メッセージ |
| **Viber** | Viberメッセージによる配信 |
| **Zalo** | Zaloメッセージによる配信(ベトナム) |> [!NOTE]
>
> 課金されるのは、メッセージを送信したときのみです。OTPが配信される前にユーザーが離脱した場合は、課金されません。→ [電話番号認証の料金](https://docs.didit.me/getting-started/phone-verification-pricing.md)


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