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

# Phone Verification Overview

> Verify phone numbers with OTP across SMS, WhatsApp, Telegram, RCS, and voice. Pay-per-call $0.04 + carrier, carrier detection, risk scoring.

export const AgentPromptAccordion = ({prompt, title = "AI Agent Integration Prompt"}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = e => {
    e.stopPropagation();
    if (!prompt) return;
    navigator.clipboard.writeText(prompt.trim()).then(() => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    });
  };
  const agents = ["Claude Code", "Codex", "Cursor", "Devin", "Windsurf", "GitHub Copilot"];
  return <div className="didit-agent-card">
      {}
      <div className="didit-agent-titlebar">
        <div className="didit-agent-dots" aria-hidden="true">
          <span className="didit-agent-dot didit-agent-dot-red"></span>
          <span className="didit-agent-dot didit-agent-dot-yellow"></span>
          <span className="didit-agent-dot didit-agent-dot-green"></span>
        </div>
        <span className="didit-agent-filename">{title}</span>
        <button type="button" className={`didit-agent-copy ${copied ? "didit-agent-copy-copied" : ""}`} onClick={handleCopy} title="Copy prompt to clipboard" aria-label={copied ? "Copied!" : "Copy prompt to clipboard"}>
          {copied ? <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <path d="M3 8.5l3.5 3.5L13 4" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" />
              </svg>
              <span>Copied</span>
            </> : <>
              <svg width="13" height="13" viewBox="0 0 16 16" fill="none">
                <rect x="5" y="5" width="9" height="9" rx="1.5" stroke="currentColor" strokeWidth="1.5" />
                <path d="M11 5V3.5A1.5 1.5 0 0 0 9.5 2h-6A1.5 1.5 0 0 0 2 3.5v6A1.5 1.5 0 0 0 3.5 11H5" stroke="currentColor" strokeWidth="1.5" />
              </svg>
              <span>Copy</span>
            </>}
        </button>
      </div>

      {}
      <pre className="didit-agent-body"><code>{prompt.trim()}</code></pre>

      {}
      <div className="didit-agent-footer">
        <span className="didit-agent-footer-label">Paste into</span>
        <div className="didit-agent-chips">
          {agents.map(name => <span key={name} className="didit-agent-chip">{name}</span>)}
        </div>
      </div>
    </div>;
};

export const VideoEmbed = ({src, title = "Video", type = "iframe"}) => <div className={type === "iframe" ? "didit-video-embed" : "didit-video-embed didit-video-native"}>
    {type === "iframe" ? <iframe src={src} title={title} style={{
  width: "100%",
  height: "100%",
  border: 0,
  borderRadius: "12px"
}} allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen /> : <video controls autoPlay muted loop playsInline src={src} title={title} style={{
  width: "100%",
  height: "auto",
  display: "block",
  borderRadius: "12px"
}} />}
  </div>;

Didit's Phone Verification provides a reliable method to verify user phone numbers through one-time passcodes (OTP). This feature adds an essential layer of security to your identity verification process, ensuring legitimate user contact information.

<AgentPromptAccordion
  title="Phone Verification Integration Prompt"
  prompt={`# 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. Powered by Prelude.

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\` — Prelude falls back to SMS if the preferred channel is unavailable. Codes are valid for **5 minutes**; one free retry per number within the window.

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 Prelude 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" — Prelude anti-abuse; 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`}
/>

<VideoEmbed src="https://www.youtube.com/embed/h0i9Q0-izcw?start=46&rel=0&playsinline=1" title="User Journey & Verification Flow" />

<Frame>
  <img src="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" alt="Phone verification flow diagram" width="3106" height="983" data-path="images/phone-verification-flow.png" />
</Frame>

## How it works

Our Phone Verification solution delivers comprehensive phone number validation through a simple, user-friendly process. The system combines OTP verification with advanced risk assessment to provide reliable phone verification at scale.

<Steps>
  <Step title="Phone Collection" icon="mobile">
    The system securely collects the following information:

    | Data Collected   | Details                                                                                                                                                       |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Phone Number** | If not provided during session creation, the user enters their phone number in international format. If provided, the user must verify the pre-filled number. |
    | **Country Code** | Automatically suggested based on IP location or user selection.                                                                                               |
    | **Carrier Type** | Detected whether mobile or landline number.                                                                                                                   |
  </Step>

  <Step title="OTP Generation & Delivery" icon="paper-plane">
    Our verification system:

    * Generates a secure, time-limited one-time passcode
    * Delivers the code via SMS to the provided number
    * Ensures optimized delivery through multiple carrier integrations
    * Provides fallback options for delivery challenges
  </Step>

  <Step title="Code Validation" icon="keyboard">
    The user completes verification by:

    * Entering the received code into the verification interface
    * Submitting within the configured timeframe (typically 5–10 minutes)
    * Requesting a new code if needed (with appropriate rate limiting)
  </Step>

  <Step title="Risk Assessment" icon="shield-halved">
    Our system performs advanced checks:

    | Check                  | Description                                               |
    | ---------------------- | --------------------------------------------------------- |
    | **Format & Carrier**   | Verifies the phone number format and carrier information. |
    | **Disposable Numbers** | Checks against known disposable/virtual number databases. |
    | **SIM Swap Detection** | Identifies potential SIM swap risks.                      |
    | **Activity Patterns**  | Detects suspicious activity patterns.                     |
    | **Historical Data**    | Cross-references with historical verification data.       |
  </Step>

  <Step title="Result Delivery" icon="bell">
    Access verification results through multiple channels:

    | Channel       | Description                                                   |
    | ------------- | ------------------------------------------------------------- |
    | **Dashboard** | Real-time dashboard updates.                                  |
    | **Webhooks**  | Instant webhook notifications.                                |
    | **API**       | RESTful API integration.                                      |
    | **Reports**   | Comprehensive reports with detailed verification information. |
  </Step>
</Steps>

## Verification Features

Our Phone Verification service offers several key features to enhance your verification process:

#### OTP Verification

* **Secure Code Generation**: Randomly generated one-time passcodes
* **SMS Delivery**: Fast and reliable delivery to mobile devices
* **Configurable Timeouts**: Set expiration times based on your security requirements
* **Retry Options**: Allow users to request new codes with appropriate rate limiting

#### Phone Number Analysis

* **Format Validation**: Ensure the phone number follows the correct international format
* **Carrier Detection**: Identify the telecommunications provider associated with the number
* **Number Type**: Distinguish between mobile, landline, and VoIP numbers
* **Country Validation**: Verify phone number matches expected country format

#### Risk Assessment

* **Disposable Number Detection**: Identify temporary numbers used to avoid traceability
* **Virtual Number Identification**: Flag numbers that may be virtual or VoIP-based
* **Activity Monitoring**: Track suspicious patterns across verification attempts
* **Blocklist Checking**: Check against internal lists of previously misused numbers

## Pricing

Phone verification is charged **per message sent** with transparent, pay-as-you-go pricing:

| Component       | Cost                          |
| --------------- | ----------------------------- |
| **Didit Fee**   | \$0.04 per verification       |
| **Carrier Fee** | Varies by country and channel |
| **Total**       | \$0.04 + carrier fee          |

We support multiple delivery channels with different pricing (availability varies by country):

| Channel      | Description                           |
| ------------ | ------------------------------------- |
| **SMS**      | Traditional text message delivery     |
| **WhatsApp** | Delivery via WhatsApp messaging       |
| **Telegram** | Delivery via Telegram messaging       |
| **RCS**      | Rich Communication Services messaging |
| **Viber**    | Delivery via Viber messaging          |
| **Zalo**     | Delivery via Zalo messaging (Vietnam) |

<Note>
  You only pay when a message is sent. If the user abandons before OTP delivery, you are not charged.
</Note>

→ [Phone Verification Pricing](/getting-started/phone-verification-pricing)