✓ Verified 💻 Development ✓ Enhanced Data

Didit Phone Verification

Integrate Didit Phone Verification standalone API to verify phone numbers via OTP.

Rating
4 (85 reviews)
Downloads
8,860 downloads
Version
1.0.0

Overview

Integrate Didit Phone Verification standalone API to verify phone numbers via OTP.

Complete Documentation

View Source →

Didit Phone Verification API

Overview

Two-step phone verification via one-time code:

  • Send a verification code to a phone number
  • Check the code the user provides
Key constraints:
  • Code expires after 5 minutes
  • Maximum 3 verification attempts per code (then must resend)
  • Maximum 2 resend requests within 24 hours
  • Rate limit: 4 sends per hour per phone number
  • Phone must be in E.164 format (e.g. +14155552671)
  • You must call Send before Check
Delivery channels: SMS (default fallback), WhatsApp, Telegram, voice call. Falls back to SMS if preferred channel unavailable.

Capabilities: Detects disposable/temporary numbers, VoIP numbers, carrier info, and duplicate numbers. Supports fraud signals for risk scoring.

API Reference: Send Code | Check Code Feature Guide: https://docs.didit.me/core-technology/phone-verification/overview

Authentication

All requests require an API key via the x-api-key header.

How to obtain: Didit Business Console → API & Webhooks → Copy API key, or via programmatic registration (see below).

text
x-api-key: your_api_key_here

Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

  • Register: POST https://apx.didit.me/auth/v2/programmatic/register/ with {"email": "[email protected]", "password": "MyStr0ng!Pass"}
  • Check email for a 6-character OTP code
  • Verify: POST https://apx.didit.me/auth/v2/programmatic/verify-email/ with {"email": "[email protected]", "code": "A3K9F2"} → response includes api_key
To add credits: GET /v3/billing/balance/ to check, POST /v3/billing/top-up/ with {"amount_in_dollars": 50} for a Stripe checkout link.

See the didit-verification-management skill for full platform management (workflows, sessions, users, billing).

Step 1: Send Phone Code

Request

text
POST https://verification.didit.me/v3/phone/send/

Headers

HeaderValueRequired
x-api-keyYour API keyYes
Content-Typeapplication/jsonYes

Body (JSON)

ParameterTypeRequiredDefaultConstraintsDescription
phone_numberstringYes—E.164 formatPhone number (e.g. +14155552671)
options.code_sizeintegerNo6Min: 4, Max: 8Code length
options.localestringNo—Max 5 charsLocale for message. e.g. en-US
options.preferred_channelstringNo"whatsapp"See channels"sms", "whatsapp", "telegram", "voice"
signals.ipstringNo—IPv4/IPv6User's IP for fraud detection
signals.device_idstringNo—Max 255 charsUnique device identifier
signals.device_platformstringNo—Enum"android", "ios", "ipados", "tvos", "web"
signals.device_modelstringNo—Max 255 charse.g. iPhone17,2
signals.os_versionstringNo—Max 64 charse.g. 18.0.1
signals.app_versionstringNo—Max 64 charse.g. 1.2.34
signals.user_agentstringNo—Max 512 charsBrowser user agent
vendor_datastringNo——Your identifier for session tracking

Example

python
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},
        "vendor_data": "session-abc-123",
    },
)

typescript
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: "sms", code_size: 6 },
  }),
});

Status Values & Handling

StatusMeaningAction
"Success"Code sentWait for user to provide code, then call Check
"Retry"Temporary issueWait a few seconds and retry (max 2 retries)
"Undeliverable"Number cannot receive messagesInform user. Try a different number
"Blocked"Number blocked (spam)Use a different number

Error Responses

CodeMeaningAction
400Invalid request bodyCheck phone format (E.164) and parameters
401Invalid or missing API keyVerify x-api-key header
403Insufficient credits/permissionsCheck credits in Business Console
429Rate limited (4/hour/number)Wait for cooldown period

Step 2: Check Phone Code

Must be called after a successful Send. Optionally auto-declines risky numbers.

Request

text
POST https://verification.didit.me/v3/phone/check/

Body (JSON)

ParameterTypeRequiredDefaultValuesDescription
phone_numberstringYes—E.164Same phone used in Step 1
codestringYes—4-8 charsThe code the user received
duplicated_phone_number_actionstringNo"NO_ACTION""NO_ACTION" / "DECLINE"Decline if already verified by another user
disposable_number_actionstringNo"NO_ACTION""NO_ACTION" / "DECLINE"Decline disposable/temporary numbers
voip_number_actionstringNo"NO_ACTION""NO_ACTION" / "DECLINE"Decline VoIP numbers

Example

python
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",
    },
)

Response (200 OK)

json
{
  "request_id": "e39cb057-...",
  "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": "ATT", "type": "mobile"},
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "sms",
    "verification_attempts": 1,
    "verified_at": "2025-08-24T09:12:39.662232Z",
    "warnings": [],
    "lifecycle": [...]
  }
}

Status Values & Handling

StatusMeaningAction
"Approved"Code correct, no policy violationsPhone verified — proceed
"Failed"Code incorrectAsk user to retry (up to 3 attempts)
"Declined"Code correct but policy violationCheck phone.warnings for reason
"Expired or Not Found"No pending codeResend via Step 1

Response Field Reference

phone Object

FieldTypeDescription
statusstring"Approved", "Failed", "Declined"
phone_number_prefixstringCountry prefix (e.g. +1)
full_numberstringFull E.164 number
country_codestringISO 3166-1 alpha-2
carrier.namestringCarrier name
carrier.typestring"mobile", "landline", "voip", "unknown"
is_disposablebooleanDisposable/temporary number
is_virtualbooleanVoIP number
verification_methodstring"sms", "whatsapp", "telegram", "voice"
verification_attemptsintegerCheck attempts made (max 3)
warningsarray{risk, log_type, short_description, long_description}

Warning Tags

TagDescriptionAuto-Decline
VERIFICATION_CODE_ATTEMPTS_EXCEEDEDMax code attempts exceededYes
PHONE_NUMBER_IN_BLOCKLISTPhone is in blocklistYes
HIGH_RISK_PHONE_NUMBERIdentified as high riskYes
DISPOSABLE_NUMBER_DETECTEDTemporary/disposable numberConfigurable
VOIP_NUMBER_DETECTEDVoIP number detectedConfigurable
DUPLICATED_PHONE_NUMBERAlready verified by another userConfigurable

Common Workflows

Basic Phone Verification

text
1. POST /v3/phone/send/   → {"phone_number": "+14155552671"}
2. Wait for user to provide the code
3. POST /v3/phone/check/  → {"phone_number": "+14155552671", "code": "123456"}
4. If "Approved"            → phone is verified
   If "Failed"              → retry (up to 3 attempts)
   If "Expired or Not Found"→ resend (step 1)

Strict Security Verification

text
1. POST /v3/phone/send/   → include signals.ip, signals.device_platform, channel: "sms"
2. POST /v3/phone/check/  → set disposable_number_action + voip_number_action to "DECLINE"
3. If "Declined" → check phone.warnings, block or warn user

Utility Scripts

bash
export DIDIT_API_KEY="your_api_key"

python scripts/verify_phone.py send +14155552671 --channel sms
python scripts/verify_phone.py check +14155552671 123456 --decline-voip

Installation

Terminal bash 

openclaw install didit-phone-verification
Copied!

💻Code Examples

x-api-key: your_api_key_here

x-api-key-yourapikeyhere.txt
## Getting Started (No Account Yet?)

If you don't have a Didit API key, create one in 2 API calls:

1. **Register:** `POST https://apx.didit.me/auth/v2/programmatic/register/` with `{"email": "[email protected]", "password": "MyStr0ng!Pass"}`
2. **Check email** for a 6-character OTP code
3. **Verify:** `POST https://apx.didit.me/auth/v2/programmatic/verify-email/` with `{"email": "[email protected]", "code": "A3K9F2"}` → response includes `api_key`

**To add credits:** `GET /v3/billing/balance/` to check, `POST /v3/billing/top-up/` with `{"amount_in_dollars": 50}` for a Stripe checkout link.

See the **didit-verification-management** skill for full platform management (workflows, sessions, users, billing).

---

## Step 1: Send Phone Code

### Request

POST https://verification.didit.me/v3/phone/send/

post-httpsverificationdiditmev3phonesend.txt
### Headers

| Header | Value | Required |
|---|---|---|
| `x-api-key` | Your API key | **Yes** |
| `Content-Type` | `application/json` | **Yes** |

### Body (JSON)

| Parameter | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `phone_number` | string | **Yes** | — | E.164 format | Phone number (e.g. `+14155552671`) |
| `options.code_size` | integer | No | `6` | Min: 4, Max: 8 | Code length |
| `options.locale` | string | No | — | Max 5 chars | Locale for message. e.g. `en-US` |
| `options.preferred_channel` | string | No | `"whatsapp"` | See channels | `"sms"`, `"whatsapp"`, `"telegram"`, `"voice"` |
| `signals.ip` | string | No | — | IPv4/IPv6 | User's IP for fraud detection |
| `signals.device_id` | string | No | — | Max 255 chars | Unique device identifier |
| `signals.device_platform` | string | No | — | Enum | `"android"`, `"ios"`, `"ipados"`, `"tvos"`, `"web"` |
| `signals.device_model` | string | No | — | Max 255 chars | e.g. `iPhone17,2` |
| `signals.os_version` | string | No | — | Max 64 chars | e.g. `18.0.1` |
| `signals.app_version` | string | No | — | Max 64 chars | e.g. `1.2.34` |
| `signals.user_agent` | string | No | — | Max 512 chars | Browser user agent |
| `vendor_data` | string | No | — | — | Your identifier for session tracking |

### Example

});

.txt
### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Success"` | Code sent | Wait for user to provide code, then call Check |
| `"Retry"` | Temporary issue | Wait a few seconds and retry (max 2 retries) |
| `"Undeliverable"` | Number cannot receive messages | Inform user. Try a different number |
| `"Blocked"` | Number blocked (spam) | Use a different number |

### Error Responses

| Code | Meaning | Action |
|---|---|---|
| `400` | Invalid request body | Check phone format (E.164) and parameters |
| `401` | Invalid or missing API key | Verify `x-api-key` header |
| `403` | Insufficient credits/permissions | Check credits in Business Console |
| `429` | Rate limited (4/hour/number) | Wait for cooldown period |

---

## Step 2: Check Phone Code

**Must be called after a successful Send.** Optionally auto-declines risky numbers.

### Request

POST https://verification.didit.me/v3/phone/check/

post-httpsverificationdiditmev3phonecheck.txt
### Body (JSON)

| Parameter | Type | Required | Default | Values | Description |
|---|---|---|---|---|---|
| `phone_number` | string | **Yes** | — | E.164 | Same phone used in Step 1 |
| `code` | string | **Yes** | — | 4-8 chars | The code the user received |
| `duplicated_phone_number_action` | string | No | `"NO_ACTION"` | `"NO_ACTION"` / `"DECLINE"` | Decline if already verified by another user |
| `disposable_number_action` | string | No | `"NO_ACTION"` | `"NO_ACTION"` / `"DECLINE"` | Decline disposable/temporary numbers |
| `voip_number_action` | string | No | `"NO_ACTION"` | `"NO_ACTION"` / `"DECLINE"` | Decline VoIP numbers |

### Example

}

.txt
### Status Values & Handling

| Status | Meaning | Action |
|---|---|---|
| `"Approved"` | Code correct, no policy violations | Phone verified — proceed |
| `"Failed"` | Code incorrect | Ask user to retry (up to 3 attempts) |
| `"Declined"` | Code correct but policy violation | Check `phone.warnings` for reason |
| `"Expired or Not Found"` | No pending code | Resend via Step 1 |

---

## Response Field Reference

### `phone` Object

| Field | Type | Description |
|---|---|---|
| `status` | string | `"Approved"`, `"Failed"`, `"Declined"` |
| `phone_number_prefix` | string | Country prefix (e.g. `+1`) |
| `full_number` | string | Full E.164 number |
| `country_code` | string | ISO 3166-1 alpha-2 |
| `carrier.name` | string | Carrier name |
| `carrier.type` | string | `"mobile"`, `"landline"`, `"voip"`, `"unknown"` |
| `is_disposable` | boolean | Disposable/temporary number |
| `is_virtual` | boolean | VoIP number |
| `verification_method` | string | `"sms"`, `"whatsapp"`, `"telegram"`, `"voice"` |
| `verification_attempts` | integer | Check attempts made (max 3) |
| `warnings` | array | `{risk, log_type, short_description, long_description}` |

---

## Warning Tags

| Tag | Description | Auto-Decline |
|---|---|---|
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | Max code attempts exceeded | Yes |
| `PHONE_NUMBER_IN_BLOCKLIST` | Phone is in blocklist | Yes |
| `HIGH_RISK_PHONE_NUMBER` | Identified as high risk | Yes |
| `DISPOSABLE_NUMBER_DETECTED` | Temporary/disposable number | Configurable |
| `VOIP_NUMBER_DETECTED` | VoIP number detected | Configurable |
| `DUPLICATED_PHONE_NUMBER` | Already verified by another user | Configurable |

---

## Common Workflows

### Basic Phone Verification

3. If "Declined" → check phone.warnings, block or warn user

3-if-declined--check-phonewarnings-block-or-warn-user.txt
---

## Utility Scripts
example.py
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},
        "vendor_data": "session-abc-123",
    },
)
example.ts
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: "sms", code_size: 6 },
  }),
});
example.py
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",
    },
)
example.json
{
  "request_id": "e39cb057-...",
  "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": "ATT", "type": "mobile"},
    "is_disposable": false,
    "is_virtual": false,
    "verification_method": "sms",
    "verification_attempts": 1,
    "verified_at": "2025-08-24T09:12:39.662232Z",
    "warnings": [],
    "lifecycle": [...]
  }
}

Tags

#coding_agents-and-ides #api

Quick Info

Category Development
Model Claude 3.5
Complexity One-Click
Author rosasalberto
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install didit-phone-verification

Resources

📂
OpenClaw Skills
View on OpenClaw GitHub
→

Related Skills

✓ Verified 💻 Development

4claw

4claw — a moderated imageboard for AI agents.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.4 (118)
↓ 4,990
v1.0.0
✓ Verified 💻 Development

Aap Passport

Agent Attestation Protocol - The Reverse Turing Test.

🧠 Claude-Ready #ai_and-llms
)}
★ 4.3 (89)
↓ 4,621
v1.0.0
✓ Verified 💻 Development

Acestep Lyrics Transcription

Transcribe audio to timestamped lyrics using OpenAI Whisper or ElevenLabs Scribe API.

⚡ GPT-Optimized #ai_and-llms #api #script
)}
★ 3.8 (274)
↓ 17,648
v1.0.0
✓ Verified 💻 Development

Adaptive Suite

A continuously adaptive skill suite that empowers Clawdbot.

🧠 Claude-Ready #ai_and-llms #bot
)}
★ 4.7 (88)
↓ 1,625
v1.0.0