Get Started
Integrate / SDKs
User Verification
Business Verification
Transaction Monitoring
ChangelogSend Email Code
Send a one-time passcode (OTP) to an email address, then verify it with POST /v3/email/check/.
How send and check pair up. Verification state is keyed by your application plus the email address — 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 address and the code the user received before the window closes. Calling send again for the same address while a verification is pending generates a fresh code for that same verification (status: "Retry", same request_id); the previous code stops working. 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.
Deliverability pre-check. Before anything is sent, the address goes through syntax and DNS/MX validation. Addresses that cannot receive mail return 200 with status: "Undeliverable" and reason: "email_can_not_be_delivered" — no email is sent, nothing is billed, and the verification is immediately finalized as Declined (a follow-up check returns Expired or Not Found). A downstream send failure reports the same way.
Code format and branding. Codes are 4–8 characters (options.code_size, default 6), numeric by default; set options.alphanumeric_code: true for uppercase letters and digits (the check comparison is case-insensitive). The email template is localized via options.locale (54 supported languages) and can use your application’s white-label branding via options.use_white_label_customization.
Billing. One Email Verification API credit per successful send (status: "Success"), charged at send time. Retry and Undeliverable sends are free, and checks are free.
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 email 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 limit. Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns 429.
Authorizations
Body
Recipient email address. Malformed addresses return 400; syntactically valid addresses that cannot receive mail (failed DNS/MX validation) return 200 with status: "Undeliverable".
"alice@example.com"
OTP format, localization, and branding options. All fields are optional.
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.
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.
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; Undeliverable means the address cannot receive mail and the verification is already finalized as Declined. request_id is the persisted session id (same id on a Retry).
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/email/check/, and can be passed to GET /v3/session/{sessionId}/decision/.
Success — OTP emailed to a new verification (billed). Retry — fresh OTP emailed for the pending verification created by a previous send (free). Undeliverable — the address failed deliverability validation or the message could not be sent; the verification is immediately finalized as Declined and nothing is billed.
Success, Retry, Undeliverable email_can_not_be_delivered when status is Undeliverable; null otherwise.
email_can_not_be_delivered, null Echo of the vendor_data stored on the session (from the first send).
Echo of the metadata stored on the session (from the first send).