Skip to main content
POST
curl

Name your brand in the SMS

SMS codes carry your application’s SMS sender name, set in the Business Console, at no extra cost:
123456 is your verification code for Acme Bank
To sign one code with a different name, pass options.sms_sender_name (1 to 30 characters: letters, digits, spaces and ’ & - ! only, not only digits):
A name outside these rules returns 400 and no code is sent. WhatsApp codes use a fixed message and are not branded; connect your own WhatsApp Business number in the Business Console to send them from your business name. See Send WhatsApp codes from your own number. See Branded verification messages for which name a code carries and the daily limit on new names.

Handle provider outages

If the phone provider is temporarily unavailable, this endpoint returns 502 with a stable machine-readable code:
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

Your application's API key, from Developers -> API keys in the Business Console. The primary key has full access. A named key can be scoped: none, read or write per resource, limited to some workflows or to approved sessions, to a list of IP addresses, and to an expiry date. 401 means the key is wrong, revoked or expired; 403 means no key was sent, the key has no access to this resource or action, or the request came from an address outside its IP list; 404 on a session route means the session is outside the key's workflows or statuses. A key without media access receives image, video and PDF URLs as null, and a key without sessions write receives session links and tokens as null. See https://docs.didit.me/console/api-keys.

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.

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.

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

Last modified on November 1, 2026