Didit Phone Verification API

Didit Phone Verification API

Overview

Three standalone endpoints:

1. Send a one-time code to a phone number: POST /v3/phone/send/
2. Check the code the user typed and get the phone report: POST /v3/phone/check/
3. Risk (no code sent): score a number in one call: POST /v3/phone/risk/

Key constraints (send + check):

• Phone numbers in E.164 (e.g. +14155552671). They are validated and normalized; invalid numbers return 400.
• The check finds the verification by your application + the phone_number. It does not take request_id.
• A pending verification lives 5 minutes from the first send. Retries do not extend it.
• One retry per pending verification: a second send for the same number inside the window returns "Retry" with the same request_id (2 sends in total). A further send starts a new verification with a new request_id.
• 3 code attempts per verification. Wrong codes 1 and 2 return "Failed"; the 3rd wrong code finalizes it as "Declined" (VERIFICATION_CODE_ATTEMPTS_EXCEEDED).
• code must be 4-8 digits (^[0-9]{4,8}$). Anything else returns 400 without using an attempt.
• Anti-abuse cap: 4 send attempts per phone number per hour (429).
• No pending verification (never sent, already finalized, blocked at send, or older than 5 minutes): the check returns HTTP 200 with status: "Expired or Not Found".
• Phone verification stays disabled until your organization's first top-up (403).
• Each new verification is stored as an API session: request_id works with GET /v3/session/{sessionId}/decision/, shows in the Business Console, and fires status.updated webhooks as it progresses.

Delivery channels: options.preferred_channel is whatsapp (default), sms, telegram, voice, rcs, viber or zalo (availability varies by country). When the preferred channel is unavailable for the number, delivery falls back to SMS and the send still reports "Success"; the channel that delivered is in phone.verification_method and in the send events of phone.lifecycle (details.actual_channel).

Branding: SMS codes carry your application's SMS sender name (set in the Business Console) at no extra cost. options.sms_sender_name signs one code with another name; options.use_white_label_customization: true uses your white-label public name when no sender name is set. WhatsApp codes use a fixed message and are not branded.

Capabilities: carrier name and line type, VoIP/virtual and disposable numbers, duplicates across your sessions (matches[]), your phone blocklist/allowlist, anti-fraud blocking at send, optional social footprint (enable_social), fraud signals.

Sandbox: sandbox API keys skip delivery, billing and persistence. Send returns a static "Success" with a random request_id; on check use code 123456 (any well-formed code returns a simplified "Approved" payload with a flat phone object). Risk returns deterministic approved data. Malformed input still returns 400.

Pricing: Phone Verification $0.04 + carrier fee per message sent, by destination country and the channel that delivers it (price table); every send except "Blocked" is billed, including "Retry"; checks are free (apart from the optional social add-on); standalone calls have no free tier. No list price is published for POST /v3/phone/risk/ (the docs say it is lower than Phone Verification) or for the social footprint add-on (enable_social, billed per request on top of the endpoint price, not billed when the lookup could not complete). These are the list prices until 1 November 2026, when Didit pricing changes and the 500 free checks a month become $10 of free credit a month. Check didit.me/pricing for current prices.

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

Authentication

Every request needs the x-api-key header. Use your application's API key from the Didit Business Console under Developers > API keys, or create an account and key programmatically (see Getting Started). Named keys with custom access need Sessions write to run standalone checks; a key limited to some workflows or to approved sessions cannot run them.