didit-phone-verification

集成 Didit 电话验证独立 API 以通过 OTP 验证电话号码。 当用户想要验证电话、发送短信、WhatsApp 或 Telegram 代码时使用， 检查电话验证码，检测一次性或 VoIP 号码，或实施 使用 Didit 进行基于电话的身份验证。支持多种配送渠道 （短信、WhatsApp、Telegram、语音）、欺诈信号和基于策略的自动拒绝。

## 概述（中文）

集成 Didit 电话验证独立 API 以通过 OTP 验证电话号码。
当用户想要验证电话、发送短信、WhatsApp 或 Telegram 代码时使用，
检查电话验证码，检测一次性或 VoIP 号码，或实施
使用 Didit 进行基于电话的身份验证。支持多种配送渠道
（短信、WhatsApp、Telegram、语音）、欺诈信号和基于策略的自动拒绝。

## 原文

# Didit Phone Verification API

## Overview

Two-step phone verification via one-time code:

1. **Send** a verification code to a phone number
2. **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](https://docs.didit.me/standalone-apis/phone-send) | [Check Code](https://docs.didit.me/standalone-apis/phone-check)
**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](https://business.didit.me) → API & Webhooks → Copy API key, or via programmatic registration (see below).

```
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:

1. **Register:** `POST https://apx.didit.me/auth/v2/programmatic/register/` with `{"email": "you@gmail.com", "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": "you@gmail.com", "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/
```

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

```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

| 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/
```

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

```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

| 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, lon