curl

curl -X POST https://verification.didit.me/v3/email/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "code": "123456",
    "disposable_email_action": "DECLINE"
  }'

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null
        },
        "fee": 0.03
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "EMAIL_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

Email Verification

Check Email Code

Verify the OTP delivered by POST /v3/email/send/ and get the final verification result plus email intelligence: deliverability, breach exposure (is_breached and the breaches list from a breach-intelligence database), disposable-provider detection, and duplicate usage of the address across your sessions.

How the check finds the verification. Matching is by your application plus the email address — request_id is not an input. The most recent pending verification created within the last 5 minutes is checked. If there is none (never sent, already finalized, undeliverable at send time, or older than 5 minutes) the endpoint returns 200 with status: "Expired or Not Found".

Attempt budget. Each verification allows 3 code attempts. The first two wrong codes return status: "Failed" with the attempts remaining and email: null; the third wrong code finalizes the verification as Declined with an EMAIL_CODE_ATTEMPTS_EXCEEDED warning and returns the full email report. Codes are compared case-insensitively (relevant for alphanumeric_code sends); only the most recently sent code is valid.

Outcomes. Approved — correct code and no declining risk. Declined — terminal: the code was correct but a declining risk matched (a DECLINE action below, a blocklisted address, or the address found undeliverable at finalization), or the attempt budget was exhausted. Failed — wrong code, attempts remaining. Expired or Not Found — nothing to check. On Approved/Declined the request_id equals the send’s request_id (the session id) and email carries the full report (is_breached, breaches, is_disposable, is_undeliverable, warnings, lifecycle, matches); on Failed and Expired or Not Found the request_id is a one-off random UUID.

Risk actions. duplicated_email_action, breached_email_action, and disposable_email_action decide what happens when the corresponding risk is detected on a correct code: DECLINE flips the final status to Declined; NO_ACTION (default) records the risk in email.warnings without affecting the status.

Billing. Checks are free — the credit is consumed by the successful send.

Session persistence. A finalized check updates the session created by the send (visible in the Business Console, queryable via GET /v3/session/{sessionId}/decision/) and fires a status.updated webhook.

Sandbox. Sandbox API keys skip all processing: code 123456 returns a static Approved payload with a simplified email object (status, email, is_breached, is_disposable, is_undeliverable); any other code returns Failed. Nothing is persisted.

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.

POST

check

curl

curl -X POST https://verification.didit.me/v3/email/check/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "alice@example.com",
    "code": "123456",
    "disposable_email_action": "DECLINE"
  }'

{
  "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24",
  "status": "Approved",
  "message": "The verification code is correct.",
  "email": {
    "status": "Approved",
    "email": "alice@example.com",
    "is_breached": false,
    "breaches": [],
    "is_disposable": false,
    "is_undeliverable": false,
    "verification_attempts": 1,
    "verified_at": "2026-06-12T01:24:47.311323Z",
    "warnings": [],
    "lifecycle": [
      {
        "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
        "timestamp": "2026-06-12T01:23:39.580554+00:00",
        "details": {
          "status": "Success",
          "reason": null
        },
        "fee": 0.03
      },
      {
        "type": "VALID_CODE_ENTERED",
        "timestamp": "2026-06-12T01:24:47.311201+00:00",
        "details": {
          "code_tried": "123456",
          "status": "Approved"
        },
        "fee": 0
      },
      {
        "type": "EMAIL_VERIFICATION_APPROVED",
        "timestamp": "2026-06-12T01:24:47.384292+00:00",
        "details": null,
        "fee": 0
      }
    ],
    "matches": []
  },
  "vendor_data": "user-1234",
  "metadata": null,
  "created_at": "2026-06-12T01:24:47.401719+00:00"
}

Authorizations

x-api-key

string

header

required

Body

application/json

string<email>

required

The same email address used in the matching POST /v3/email/send/ call. This is what links the check to the send.

Example:

"alice@example.com"

code

string

required

The OTP the end user received: 4–8 digits, or 4–8 letters/digits when alphanumeric_code: true was used at send time. Comparison is case-insensitive.

Maximum string length: 10

Example:

"123456"

duplicated_email_action

enum<string>

default:NO_ACTION

What to do when the same address was already used and approved by a different user (only previously Approved verifications count) (different vendor_data) of your application. DECLINE flips the final status to Declined; NO_ACTION records the risk in email.warnings and fills email.matches.

Available options:

NO_ACTION,

DECLINE

breached_email_action

enum<string>

default:NO_ACTION

What to do when the address appears in known data breaches (email.is_breached). DECLINE flips the final status to Declined; NO_ACTION records the risk in email.warnings.

Available options:

NO_ACTION,

DECLINE

disposable_email_action

enum<string>

default:NO_ACTION

What to do when the domain belongs to a disposable/temporary-mail provider (email.is_disposable). DECLINE flips the final status to Declined; NO_ACTION records the risk in email.warnings.

Available options:

NO_ACTION,

DECLINE

Response

Check completed — wrong codes and missing verifications also return 200; inspect status, not the HTTP code. email is populated only on finalized outcomes (Approved/Declined), null on Failed, and absent on Expired or Not Found.

request_id

string<uuid>

On Approved/Declined: the session id of the matched verification — identical to the request_id returned by POST /v3/email/send/. On Failed and Expired or Not Found: a random one-off UUID that cannot be looked up later.

status

enum<string>

Approved — correct code, no declining risk. Declined — terminal: a declining risk matched or the attempt budget (3) was exhausted. Failed — wrong code, attempts remaining. Expired or Not Found — no pending verification for this address in the last 5 minutes.

Available options:

Approved,

Declined,

Failed,

Expired or Not Found

message

string

Human-readable explanation of the outcome, including the number of attempts remaining after a wrong code.

object

Full email report. Present (non-null) only on finalized outcomes (Approved/Declined); null on Failed and absent on Expired or Not Found.

Show child attributes

vendor_data

string | null

vendor_data of the matched verification's session. null on Expired or Not Found.

metadata

object

metadata of the matched verification's session. null on Expired or Not Found.

created_at

string<date-time>

Timestamp of this check response.

Send Email Code Overview

⌘I