/Send a verification

API docs

Send a verification

Create a verification to deliver a one-time passcode. OTPRelay generates the code and sends the SMS from the OTPRelay sender, with automatic route failover.

POST/v1/verifications

You only need to. Everything else has a sensible default - OTPRelay generates the code and sends the SMS from the OTPRelay sender. The response is a verification object with status: "pending".

The sender is always OTPRelay and the message template is fixed - see Sender & message.

Prefer to generate your own code? Use Send a code instead - OTPRelay just delivers it.

Request body

tostringrequired
The destination phone number in E.164 format, e.g. +966512345678.
code_lengthintegeroptional
Number of digits in the code, 4-8. Defaults to 6.
expiryintegeroptional
Time-to-live for the code in seconds, 60-3600. Defaults to 600 (10 minutes).
custom_codestringoptional
A pre-generated code (sandbox or migration use). Requires custom codes enabled on the account.
webhook_urlstringoptional
An HTTPS URL to receive this verification's events. See Webhooks & events.
metadataobjectoptional
Up to 10 key/value pairs echoed back on the verification and its webhook events.

Request

POST /v1/verifications
curl https://api.otprelay.io/v1/verifications \  -H "Authorization: Bearer sk_live_••••" \  -H "Content-Type: application/json" \  -d '{    "to": "+966512345678",    "code_length": 6,    "webhook_url": "https://api.yourapp.com/otp/webhook"  }'

Response

Returns 201 Created with the verification. Inspect attempts[] to see which carrier each SMS send used, including any automatic route failover.

201 Created
{  "id": "ver_01HZX9Q2K3M7B8N4P5R6S7T8U9",  "object": "verification",  "status": "pending",  "to": "+966512345678",  "country": "SA",  "sender": "OTPRelay",  "code_length": 6,  "verified": false,  "webhook_url": "https://api.yourapp.com/otp/webhook",  "attempts": [    {      "id": "att_01HZX9Q2K3M7B8N4P5R6S7T8UA",      "status": "sent",      "carrier": "stc",      "at": "2026-06-16T10:00:00Z"    }  ],  "metadata": { "user_id": "u_8842" },  "created_at": "2026-06-16T10:00:00Z",  "expires_at": "2026-06-16T10:10:00Z"}

Send limits

A verification accepts up to 5 sendsto the same number before it's closed (max_send_attempts). Re-sending within the expiry window delivers the samecode - it doesn't generate a new one.

Next, check the code the user entered.