Skip to main content
POST
curl

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

Body

application/json
phone_number
string
required

The same phone number used in the matching POST /v3/phone/send/ call, in E.164 format. This is what links the check to the send.

Maximum string length: 20
Example:

"+14155552671"

code
string
required

The OTP the end user received. Must be 4–8 numeric digits — anything else returns 400 without consuming an attempt. A well-formed but wrong code returns 200 with status: "Failed" and consumes one of the 3 attempts.

Required string length: 4 - 8
Pattern: ^[0-9]{4,8}$
Example:

"123456"

duplicated_phone_number_action
enum<string>
default:NO_ACTION

What to do when the same number was already used by a different user (different vendor_data) of your application. DECLINE flips the final status to Declined; NO_ACTION records the risk in phone.warnings and fills phone.matches.

Available options:
NO_ACTION,
DECLINE
disposable_number_action
enum<string>
default:NO_ACTION

What to do when the carrier lookup flags the number as a temporary/burner line (phone.is_disposable). DECLINE flips the final status to Declined; NO_ACTION records the risk in phone.warnings.

Available options:
NO_ACTION,
DECLINE
voip_number_action
enum<string>
default:NO_ACTION

What to do when the carrier lookup reports a virtual line type — voip, isp, or vpn (phone.is_virtual). DECLINE flips the final status to Declined; NO_ACTION records the risk in phone.warnings.

Available options:
NO_ACTION,
DECLINE

Response

Check completed — wrong codes and missing verifications also return 200; inspect status, not the HTTP code. phone 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/phone/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 number 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.

phone
object | null

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

vendor_data
string | null

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

metadata
object | null

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

created_at
string<date-time>

Timestamp of this check response.