Phone Verification Report: OTP & Carrier JSON

The Phone Verification report captures the full outcome of a phone OTP challenge: who we sent the code to, which carrier and channel handled it, how many attempts it took, whether the number is disposable or VoIP, and any cross-session matches against your blocklist or other users’ sessions. This page documents the JSON shape returned by the decision endpoint so you can parse OTP outcomes, carrier metadata, and risk flags for each verified number.

Didit phone verification report showing OTP outcome, carrier metadata and risk flags

Overview

A phone report is produced every time a workflow node runs the Phone Verification feature. Each report represents one OTP challenge against one phone number and contains:

The phone number broken into prefix, national number and full E.164 form, plus ISO country code and country name.
Carrier metadata (name, type) resolved from the destination network.
Boolean risk flags (is_disposable, is_virtual) derived from line-type analysis.
The actual delivery channel used (verification_method) and the count of OTP send attempts.
A chronological lifecycle[] log of every send, retry, delivery event, and code-check attempt, each delivery event naming the send it belongs to and, when the message was not delivered, why.
A matches[] array surfacing the same number on other sessions — any status, across KYC, KYB and standalone API verifications — or your blocklist.
A warnings[] array — risk events emitted during the verification (see Phone Verification warnings).
A node_id that identifies which workflow graph node produced the report (V3 sessions only).

In hosted verification flows Didit runs the OTP exchange for you. For direct API integrations the same flow is two calls — POST /v3/phone/send/ to deliver the code and POST /v3/phone/check/ to validate the user’s entry. A pending OTP is valid for 5 minutes from the first send (retries do not extend the window). In workflow sessions users get 2 OTP send attempts (phone_max_retries) and 2 code-entry attempts (phone_max_check_attempts) by default — both tunable per workflow node; exhausting either cap finalizes the step as Declined with VERIFICATION_CODE_ATTEMPTS_EXCEEDED. The standalone phone API allows 3 code-entry attempts per verification.

Where it appears in API responses

The decision endpoint (GET /v3/session/{sessionId}/decision/) returns phone reports under the plural array key phone_verifications. The array contains one entry per Phone Verification node in the workflow graph — typically one, but step-up flows may produce several.

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}

A null value means no Phone Verification step has run yet. Iterate the array (rather than reading phone_verifications[0]) when your workflow can collect more than one phone number.

Schema

The canonical field-by-field schema lives on the Data models page.

interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}

Status values

Status	Meaning
`Not Finished`	The OTP send has been initiated but the verification has not been finalized yet.
`Approved`	The user entered a valid OTP and no declining risk matched.
`Declined`	An auto-decline warning fired (blocklist, high-risk, attempts exceeded) or a risk action configured to `DECLINE` matched.
`In Review`	A risk action configured to `REVIEW` routed the step to manual review.
`Expired`	The 5-minute OTP window elapsed with no valid code — applies to verifications created via the standalone phone API.

Lifecycle event types

lifecycle[] is sorted chronologically. Each event has type, timestamp, details, and a billable fee (when applicable):

Event type	Emitted when
`PHONE_VERIFICATION_MESSAGE_SENT`	First OTP send attempt over the requested channel.
`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`	Subsequent OTP send after the user requested a resend.
`PHONE_VERIFICATION_BLOCKED`	The send was blocked (spam, suspicious, repeated, invalid number).
`PHONE_DELIVERY_DELIVERED`	Carrier confirmed delivery on the actual channel used.
`PHONE_DELIVERY_UNDELIVERABLE`	Carrier reported the message could not be delivered, with a `reason`.
`VALID_CODE_ENTERED`	The user submitted the correct OTP code.
`INVALID_CODE_ENTERED`	The user submitted an incorrect OTP code (counts toward the code-entry cap).
`PHONE_VERIFICATION_APPROVED`	Feature-level status was set to `Approved`.
`PHONE_VERIFICATION_DECLINED`	Feature-level status was set to `Declined`.
`PHONE_VERIFICATION_IN_REVIEW`	Feature-level status was set to `In Review`.
`PHONE_VERIFICATION_EXPIRED`	The OTP window elapsed without a valid code.

The details payload depends on the event family:

Send events (PHONE_VERIFICATION_MESSAGE_SENT, PHONE_VERIFICATION_RETRY_MESSAGE_SENT, PHONE_VERIFICATION_BLOCKED) — { status, reason, channel, actual_channel, attempt, delivery_status }. status is Success, Retry or Blocked; reason is null unless the send was blocked (invalid_phone_number, repeated_attempts, suspicious, spam, unknown); channel is the requested channel and actual_channel the channel that actually delivered (e.g. a WhatsApp send that fell back to SMS); attempt is the 0-based index of this send, in the same order as the send events. delivery_status is how the send ended — delivered, undeliverable, or unknown when the verification ended and no delivery report had arrived — and is absent while a report can still arrive.
Delivery events (PHONE_DELIVERY_DELIVERED, PHONE_DELIVERY_UNDELIVERABLE) — { channel, status, attempt, reason } with status delivered or undeliverable. attempt is the index of the send the report belongs to, so a report that arrives after the code was entered (an earlier send expiring, a fallback attempt failing) is not mistaken for the code itself not arriving. reason appears on PHONE_DELIVERY_UNDELIVERABLE only, and is one word from the table below; a call’s channel is voice and its reason is one of the four call words.
Check events (VALID_CODE_ENTERED, INVALID_CODE_ENTERED) — { code_tried, status } with status Approved, Declined, Failed or Expired or Not Found.
Final status events — null, except PHONE_VERIFICATION_DECLINED / PHONE_VERIFICATION_IN_REVIEW, which carry { "reason": "<risk code>" } (e.g. PHONE_NUMBER_IN_BLOCKLIST).

reason on a PHONE_DELIVERY_UNDELIVERABLE event is a fixed, customer-safe word. It is never a provider name, a provider status or a raw error code, so it is safe to show to support teams and end users as it is.

`reason`	Channel	Meaning
`expired`	Message	The message was not delivered within the window the carrier or messaging app allows, and expired.
`rejected`	Message	The carrier or messaging app refused the message: it never left.
`unreachable`	Message	The report says the message never reached the handset (switched off, no coverage, an unknown or disconnected number).
`blocked`	Message	The number, the sender or the account may not receive it: a blocklist, an opt-out, a spam refusal or a policy restriction.
`unknown`	Message	A failure was reported without a reason Didit can name.
`unreachable_number`	Call	The call could not be placed, or the number is not in service: it does not exist or is not a valid number.
`no_answer`	Call	The call rang and nobody answered before the ring time ran out.
`busy`	Call	The line was busy.
`undeliverable`	Call	The call ended without the code being read for another reason, for example the call was rejected or the network dropped it.

A call answers one of the four call words and never a message word, so the reason on the event is the same word the phone step shows the user while they wait for the code. fee on a send event is the total price of that send: the carrier or WhatsApp price plus the $0.02 Didit fee, or only the $0.02 Didit fee for a WhatsApp code sent from your own WhatsApp Business number. It is the estimated price until delivery is confirmed, then the actual billed amount. Only Blocked sends are guaranteed free: any other send is charged when the verification finalizes or expires, even if delivery was never confirmed or the message was undeliverable. Delivery, check and status events always carry fee: 0.

Cross-session matches

matches[] records other sessions in the same application where the same number was seen — across KYC, KYB and standalone API verifications, regardless of their status — plus blocklist hits configured in the management-api lists. Sessions sharing the current session’s vendor_data are excluded (the same end-user does not match themselves), and the array is capped at 5 entries. When the number is on your blocklist but none of the matched sessions is blocklisted, a synthetic entry with source: "list_entry" (all session fields null) is prepended to the array.

interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}

Examples

Approved — WhatsApp OTP, mobile carrier

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp", "attempt": 0, "delivery_status": "delivered" },
      "fee": 0.0509
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered", "attempt": 0 },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}

Declined — blocklisted VoIP number

The user entered a valid OTP, but finalization found the number on the application’s blocklist (auto-decline) and flagged its VoIP line type (voip_number_action left at NO_ACTION, so it logs as information). Because no matched session is blocklisted, the blocklist hit appears as a synthetic list_entry match.

{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms", "attempt": 0, "delivery_status": "unknown" },
      "fee": 0.0509
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}

Phone Verification overview — feature behavior, pricing, supported channels.
Phone Verification warnings — every risk code, decline triggers and configurable actions.
Data models — phone verification — canonical field-by-field schema.
Standalone phone API — POST /v3/phone/send/ and POST /v3/phone/check/ endpoints.
Management API — Lists — manage the phone blocklist that feeds matches[] with source: list_entry.

Authentication

Verification

Monitoring

Platform

Phone Verification Report: OTP & Carrier JSON

Overview

Where it appears in API responses

Schema

Status values

Lifecycle event types

Cross-session matches

Examples

Approved — WhatsApp OTP, mobile carrier

Declined — blocklisted VoIP number

Overview

Where it appears in API responses

Schema

Status values

Lifecycle event types

Cross-session matches

Examples

Approved — WhatsApp OTP, mobile carrier

Declined — blocklisted VoIP number

Related