Verify

API reference · v1

One call to send, one to check.

Plain JSON over HTTPS. Call it from your server only.

00

Authentication

Send your key in the Authorization header: Bearer ov_live_… Test keys (ov_test_…) send nothing and accept 000000.

Every error is problem details (RFC 9457) with a plain-language title and detail.

01

Check the API is up

GET/v1/health

Returns ok when the API is running. Needs no API key.

Responses

  • 200The API is up.

200

status"ok" · required
versionstring · required
"2026-11-01.abc1234"
02

Send a code

POST/v1/verify/send

Creates a 6-digit code and sends it on WhatsApp from your own number, then by SMS if WhatsApp does not deliver in time. Send an Idempotency-Key header so a retry never sends twice. Test keys (ov_test_) send nothing and accept 000000.

Request body

tostring · required
The phone number in E.164 format."+966512345612"
locale"ar" | "en"
Message language. Defaults to your organisation's default.
channel"auto" | "whatsapp" | "sms"
auto = WhatsApp first, then SMS if not delivered in time.
end_user_ipstring (ip)
Your end user's IP. Strongly recommended: lets us rate-limit per user."203.0.113.7"
appstring
Reserved for choosing a saved Android app for one-tap autofill.

Responses

  • 202Accepted. The code is on its way.
  • 401Missing or invalid API key.
  • 402Monthly plan limit reached.
  • 403The key lacks the needed scope.
  • 409A request with this Idempotency-Key is still running.
  • 422The request did not pass checks.
  • 429Rate limited. See Retry-After.

202

idstring · required
"ver_0193f2c48a1b7c3d9e4f0123456789ab"
status"pending" · required
channel"whatsapp" | "sms" · required
expires_atstring (date-time) · required
03

Check a code

POST/v1/verify/check

Compares the code your user typed. Each code works once and locks after too many wrong tries.

Request body

idstring · required
"ver_0193f2c48a1b7c3d9e4f0123456789ab"
codestring · required
"482913"

Responses

  • 200The result.
  • 401Missing or invalid API key.
  • 403The key lacks the needed scope.
  • 404No such verification for this key.
  • 409The code was already used.
  • 422The request did not pass checks.
  • 429Rate limited. See Retry-After.

200

idstring · required
"ver_0193f2c48a1b7c3d9e4f0123456789ab"
status"approved" | "denied" | "expired" | "locked" | "failed" · required
attempts_remaininginteger
Only when status is denied.
04

Read a verification

GET/v1/verify/{id}

Status and delivery history, without the code. Useful for support teams.

Responses

  • 200The verification.
  • 401Missing or invalid API key.
  • 403The key lacks the needed scope.
  • 404No such verification for this key.

200

idstring · required
"ver_0193f2c48a1b7c3d9e4f0123456789ab"
status"pending" | "approved" | "expired" | "locked" | "failed" · required
channel"whatsapp" | "sms" · required
tostring · required
Masked. We never return the full number."+966 •••••••12"
countrystring · required
"SA"
environment"live" | "test" · required
attemptsinteger · required
created_atstring (date-time) · required
expires_atstring (date-time) · required
completed_atstring,null (date-time) · required
deliveriesobject[] · required