Check message_id Status

Delivery report for a sent OTP, plus whether the code is still active.

Delivery receipts arrive a few seconds after the send, so the first call after /generate_otp normally reports a pending state rather than a carrier status. Poll every few seconds, and treat any DLR value beginning "Pending:" as "ask again shortly". If you would rather not poll at all, register a delivery webhook in the dashboard and we will POST each status change to you instead.

Data is retained for 24 hours after an OTP expires.

post/check_otp_status

Request

  • Base URL: https://api.myotp.app
  • URL: https://api.myotp.app/check_otp_status
  • Auth: none declared. Required headers: X-API-Key

Headers

X-API-Keystring required

Request body

message_idstring required

The message ID returned by /generate_otp.

Response

The delivery report, or an explanation of why one is not available. Note that an unknown message_id is also a 200, carrying "message" instead of "DLR".

DLRstring

The delivery state. Values fall into four groups.

Carrier status, passed through verbatim, for SMS: ATES (accepted by the carrier), DELIVRD (delivered), UNDELIV, EXPIRED, REJECTD. For WhatsApp and Telegram this is our own transaction status instead: sent, delivered, read, pending, or a failed.<reason> code.

Pending, meaning try again in a few seconds: "Pending: not yet accepted by the carrier" (the send has not been acknowledged yet) and "Pending: the carrier has not reported yet" (accepted, no receipt yet).

Failures are reported as failed.<reason>. On WhatsApp the reason is one of two values: failed.Undeliverable, meaning the number cannot receive WhatsApp, which is permanent and is your signal to fall back to SMS, and failed.Provider, meaning the send failed on our side or the carrier's, which is worth retrying. SMS reasons name the stage that failed, for example failed.NoBalance or failed.SMPP. A bare failed predates the WhatsApp reasons and should be read as failed.Provider.

Unavailable, which are statements about your plan or the route rather than this message: "Not available with your plan" (your plan has no DLR_ACCESS entitlement), "Not available for this market" (the route reports nothing back) and "Not available from the carrier" (the carrier declined to answer).

is_activeboolean

Whether the OTP can still be verified, i.e. it has not expired.

expires_atstring date-time

When the OTP expires. Absent when the message_id is unknown.

messagestring

Present instead of DLR when the message_id is not found. Data is available for 24 hours after an OTP expires.

DLR:string

Deprecated alias of DLR, kept so existing integrations keep working. Read DLR instead; this key will be removed.

Message:string

Deprecated alias of message. Read message instead.

Example response

{
  "DLR": "DELIVRD"
}

Changes

No recorded changes to this operation across all 1 revision of this API.