curl

curl -X POST https://verification.didit.me/v3/phone/send/ \
  -H 'x-api-key: YOUR_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"
  }'

import os, requests

resp = requests.post(
    "https://verification.didit.me/v3/phone/send/",
    headers={
        "x-api-key": os.environ["DIDIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "+14155552671",
        "options": {
            "code_size": 6,
            "preferred_channel": "whatsapp",
            "locale": "en-US",
        },
        "vendor_data": "user-1234",
    },
    timeout=15,
)
resp.raise_for_status()
print(resp.json())  # {request_id, status, reason, vendor_data, metadata}
# Then verify with POST /v3/phone/check/ using the same phone_number

const res = 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: { code_size: 6, preferred_channel: 'whatsapp', locale: 'en-US' },
    vendor_data: 'user-1234',
  }),
});
if (!res.ok) throw new Error(`Phone send failed: ${res.status}`);
const data = await res.json();
console.log(data); // { request_id, status, reason, vendor_data, metadata }
// Then verify with POST /v3/phone/check/ using the same phone_number

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/phone/send/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number' => '+14155552671',
    'options' => [
        'preferred_channel' => 'whatsapp',
        'locale' => 'en-US'
    ],
    'vendor_data' => 'user-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/phone/send/"

	payload := strings.NewReader("{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/phone/send/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/phone/send/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Success",
  "reason": null,
  "vendor_data": "user-1234",
  "metadata": null
}

Phone Verification

Send Phone Code

Send a one-time passcode (OTP) to a phone number over WhatsApp, SMS, or another supported channel, then verify it with POST /v3/phone/check/.

How send and check pair up. Verification state is keyed by your application plus the E.164 phone_number — the check call does not take request_id. Each new send creates a pending verification that lives for 5 minutes: call the check with the same number and the code the user received before the window closes. Calling send again for the same number while a verification is pending re-sends a code for that same verification (status: "Retry", same request_id). At most one retry is attached this way (two sends total); a further send starts a fresh verification with a new request_id. The 5-minute window is measured from the first send and is not extended by retries.

Delivery channels. options.preferred_channel selects the channel (whatsapp by default; sms, telegram, voice, rcs, viber, and zalo are also supported). When the preferred channel is unavailable for the destination country or number, delivery automatically falls back to SMS — the send still reports Success, and the channel actually used is reported by the check response (phone.verification_method and the lifecycle events).

Send statuses. Success — OTP sent for a new verification; Retry — OTP re-sent for the pending verification; Blocked — the anti-fraud layer refused to send (see reason, e.g. repeated_attempts, suspicious, spam). A Blocked send immediately finalizes the verification as Declined with a high-risk warning, so a follow-up check returns Expired or Not Found.

Billing. The price depends on the destination country and the channel that actually delivers the message — see Phone Verification Pricing. Only Blocked sends are guaranteed free: any other unbilled send attempt is charged at verification finalization or expiration, even if delivery was never confirmed or the delivery provider reported the message undeliverable. Checks are always free. As an anti-abuse measure, phone verification is disabled until your organization’s first top-up (403).

Session persistence. Every new verification is persisted as an API-type session: request_id is a real session id you can pass to GET /v3/session/{sessionId}/decision/, the verification appears in the Business Console, and status.updated webhooks fire as it progresses.

Sandbox. Sandbox API keys skip delivery and billing: after request validation (malformed input still returns 400), the endpoint returns a static Success payload with a random request_id; no message is sent and nothing is persisted. Use code 123456 on the sandbox check.

Authentication. Send your application’s API key in the x-api-key header. Missing or invalid credentials return 403 ({"detail": "You do not have permission to perform this action."}) — this API never returns 401.

Rate limits. Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints, plus an anti-abuse cap of 4 send attempts per phone number per hour; exceeding either returns 429.

POST

phone

send

curl

curl -X POST https://verification.didit.me/v3/phone/send/ \
  -H 'x-api-key: YOUR_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"
  }'

import os, requests

resp = requests.post(
    "https://verification.didit.me/v3/phone/send/",
    headers={
        "x-api-key": os.environ["DIDIT_API_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "phone_number": "+14155552671",
        "options": {
            "code_size": 6,
            "preferred_channel": "whatsapp",
            "locale": "en-US",
        },
        "vendor_data": "user-1234",
    },
    timeout=15,
)
resp.raise_for_status()
print(resp.json())  # {request_id, status, reason, vendor_data, metadata}
# Then verify with POST /v3/phone/check/ using the same phone_number

const res = 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: { code_size: 6, preferred_channel: 'whatsapp', locale: 'en-US' },
    vendor_data: 'user-1234',
  }),
});
if (!res.ok) throw new Error(`Phone send failed: ${res.status}`);
const data = await res.json();
console.log(data); // { request_id, status, reason, vendor_data, metadata }
// Then verify with POST /v3/phone/check/ using the same phone_number

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://verification.didit.me/v3/phone/send/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phone_number' => '+14155552671',
    'options' => [
        'preferred_channel' => 'whatsapp',
        'locale' => 'en-US'
    ],
    'vendor_data' => 'user-1234'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://verification.didit.me/v3/phone/send/"

	payload := strings.NewReader("{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://verification.didit.me/v3/phone/send/")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://verification.didit.me/v3/phone/send/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"phone_number\": \"+14155552671\",\n  \"options\": {\n    \"preferred_channel\": \"whatsapp\",\n    \"locale\": \"en-US\"\n  },\n  \"vendor_data\": \"user-1234\"\n}"

response = http.request(request)
puts response.read_body

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Success",
  "reason": null,
  "vendor_data": "user-1234",
  "metadata": null
}

Handle provider outages

If the phone provider is temporarily unavailable, this endpoint returns 502 with a stable machine-readable code:

{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}

Treat this response as retryable. Use a short backoff and show the user a temporary-service message instead of asking them to change a valid phone number or code.

Authorizations

x-api-key

string

header

required

Body

application/json

phone_number

string

required

Recipient phone number in E.164 format — leading + and country code (e.g., +14155552671). Numbers are validated and normalized to E.164; unparseable or invalid numbers return 400 with a phone_number field error.

Maximum string length: 20

Example:

"+14155552671"

options

object

OTP delivery options. All fields are optional.

Show child attributes

signals

object

Optional device and network signals about the end user, forwarded to the anti-fraud layer to improve detection of abusive or automated traffic. All fields are optional.

Show child attributes

vendor_data

string

Optional caller-controlled identifier (your internal user id, an email, a UUID, etc.) persisted on the session and echoed back in the send response, the matching check response, webhooks, and the Business Console. Use it to correlate Didit's request_id with your user record.

metadata

object | null

Optional free-form JSON object persisted on the session and echoed back in the send response, the matching check response, webhooks, and the Business Console.

Response

Send acknowledged. Inspect status: Success and Retry mean a code is on its way; Blocked means the anti-fraud layer refused and the verification is already finalized as Declined. request_id is the persisted session id (same id on a Retry).

request_id

string<uuid>

Session id of the verification. A Retry send returns the same request_id as the original send. This id appears in the Business Console, is returned again by a finalized POST /v3/phone/check/, and can be passed to GET /v3/session/{sessionId}/decision/.

status

enum<string>

Success — OTP sent to a new verification. Retry — OTP re-sent for the pending verification created by a previous send. Blocked — the anti-fraud layer refused to send; the verification is immediately finalized as Declined and nothing is billed.

Available options:

Success,

Retry,

Blocked

reason

string | null

Why a send was Blocked (e.g., repeated_attempts, suspicious, spam). null on Success and Retry.

vendor_data

string | null

Echo of the vendor_data stored on the session (from the first send).

metadata

object | null

Echo of the metadata stored on the session (from the first send).

⌘I

Overview

User and Business Verifications

Lists

Workflows

Questionnaires

Users

Businesses

Cases

Case Blueprints

Report Templates

Regulatory Reports

Transactions

Travel Rule

Session Operations

Customization

Webhook

Billing

Management API Overview

Auth API (Programmatic)

Identity & Documents

Database Validation

Biometrics & Face

Compliance & Risk

Email Verification

Phone Verification

Send Phone Code

Handle provider outages

Authorizations

Body

Response

​Handle provider outages

Authorizations

Body

Response

Handle provider outages