Check OTP Status

Check the status of an active OTP for a phone number without verifying it.

This is a non-destructive endpoint — it does not increment attempt counters or consume the OTP. Use it to display status information in your UI (expiry timer, remaining attempts, etc.) before the user submits their code.

Required Scope

messages:send

Use Cases

Display an expiry countdown timer in your UI

Show remaining verification attempts to the user

Determine if a resend is needed (OTP expired or max attempts reached)

Pre-check before showing the OTP input form

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Header Params

Body Params application/jsonRequired

Example

{
    "phone": "+201XXXXXXXXX",
    "purpose": "authentication"
}

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢200Success

application/json

Body

Example

{
    "success": true,
    "data": {
        "has_active_otp": true,
        "expires_at": "2026-01-01T08:03:14+00:00",
        "expires_in_seconds": 600,
        "is_expired": false,
        "verification_attempts": 0,
        "max_attempts": 5,
        "attempts_remaining": 5,
        "created_at": "2026-01-01T07:53:14+00:00"
    },
    "message": "OTP status retrieved successfully",
    "meta": {
        "request_id": "544e6133-a7ab-4bfa-9d28-85b168d98523",
        "timestamp": "2026-01-01T07:58:39+00:00"
    }
}

🟠401UNAUTHORIZED

🟠403INSUFFICIENT_SCOPE

🟠403FEATURE_LIMIT_EXCEEDED

🟠404NOT_FOUND

🟠422VALIDATION_ERROR

🟠422WHATSAPP_NOT_CONFIGURED

🟠429RATE_LIMIT_EXCEEDED

🔴500INTERNAL_ERROR