Verify & OTP

Verify is a messaging-based one-time code primitive. Your backend asks Wave to send a verification code to a phone number over WhatsApp; the user reads and submits it; you check the code and get a trustworthy, machine-readable verdict over a signed webhook (and a status API). It’s a phone-possession factor for signup, step-up auth, and password reset — a security primitive, not a menu-tree IVR. Because the outcome gates access, it is fail-closed by design: only an exact, in-time, in-attempt-budget code grants, and a wrong or expired code never does.

This is an API-triggered, outbound flow (Wave sends the user a code). It is distinct from Voice Authentication (a call-to-approve primitive). Verify is gated — ask your Wave contact to enable it for your account.

Authentication & tiers

Every /v1/verify endpoint needs a production API key (sk_live_) with the verify:write scope (or verify:read for status). Sandbox keys can’t send real verification codes.

Create a verification

curl https://api.wave.sa/v1/verify \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 4e1a…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+9665XXXXXXXX",
    "channel": "whatsapp",
    "locale": "ar",
    "ttl_seconds": 300,
    "metadata": { "ref": "REF-8842" }
  }'

Field	Required	Notes
`phone_number`	✅	E.164 (`+9665…`). The number Wave sends the code to.
`channel`	—	`whatsapp` (default). The delivery channel.
`locale`	—	`ar` (default) or `en` — the message language.
`ttl_seconds`	—	60–900, default 300. The code expires after this.
`idempotency_key`	—	Send it as the `Idempotency-Key` header; a repeat returns the same verification without a second code minted or second message sent.
`metadata`	—	Opaque; echoed back in the webhook.

201 returns the verification id and its expiry:

{ "verification_id": "ver_9f1c…", "state": "initiated", "expires_at": "2026-09-01T12:05:00Z" }

The verdict — fail closed

A verification resolves to exactly one terminal state:

State	Meaning	Grants access?
`verified`	The user submitted the correct code in time	✅ yes
`failed`	The code was wrong (attempt limit exhausted)	no
`expired`	No valid check before `expires_at`	no
`max_attempts`	Five wrong attempts reached	no
`canceled`	Superseded by a new verification to the same number	no

Only verified grants access. Treat every other state as a non-grant and fail closed. Always confirm the verdict via the status API (below) before honoring an approval — defense in depth.

Check the code

curl https://api.wave.sa/v1/verify/check \
  -H "Authorization: Bearer sk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "ver_9f1c…",
    "code": "123456"
  }'

Field	Required	Notes
`verification_id`	✅	From the create response.
`code`	✅	The 6-digit code the user entered.

200 returns the verification state and a boolean verdict:

{ "verification_id": "ver_9f1c…", "state": "verified", "verified": true }

On a wrong code, the response carries state: "awaiting_check" and verified: false; the attempt counter increments. After five wrong attempts, state becomes max_attempts and further checks fail with state: "max_attempts".

The result webhook

On a terminal state Wave sends a signed verify.completed event to your project’s webhook endpoint:

{
  "event": "verify.completed",
  "data": {
    "verification_id": "ver_9f1c…",
    "state": "verified",
    "decided_at": "2026-09-01T12:02:10Z",
    "attempts": 1,
    "channel": "whatsapp"
  }
}

Verify every delivery:

X-Wave-Signature — sha256=…, an HMAC-SHA256 of the raw body with your endpoint’s signing secret. Reject a mismatch.
X-Wave-Timestamp — unix seconds; reject deliveries older than your window (e.g. 5 minutes).
X-Wave-Event-Id — stable across retries; dedupe on it.

The webhook is a notification — reconfirm via the status API before granting.

Poll status

curl https://api.wave.sa/v1/verify/ver_9f1c… \
  -H "Authorization: Bearer sk_live_…"

Returns the current state, attempts, channel, timestamps, and (once terminal) the decision. Scoped to your organization only.

One code per number, code expiry & idempotency

One live code per number — a new POST /v1/verify to the same number supersedes the previous code and cancels the old verification.
Code expiry — a code expires at expires_at. A check after expiry returns state: "expired" and does not increment attempts.
Idempotency — send an Idempotency-Key; a retry with the same key returns the same verification and never mints a second code or sends a second message.

Rate limits & abuse controls

Per-number limits — Wave caps verifications to a single number per API key, and blocks known-abusive numbers/prefixes, to prevent code-bombing and toll fraud. Over a limit → 429.
Per-verification attempt cap — five wrong attempts → max_attempts. No further checks are accepted.
Global volume limits — Wave tracks overall verification volume per API key. Sustained excess → 429.

Errors

Code	HTTP	When
`VERIFY_DISABLED`	503	Not enabled for this account
`SANDBOX_KEY_NOT_ALLOWED`	400	A sandbox key was used
`VALIDATION_ERROR`	400	Bad phone/locale/ttl
`VERIFY_BLOCKED`	403	The target number is blocklisted
`VERIFY_RATE_LIMITED`	429	A per-number/per-originator limit was hit
`VERIFY_NOT_FOUND`	404	No such verification for your organization
`INVALID_CODE`	400	The code is malformed or wrong
`MAX_ATTEMPTS_EXCEEDED`	400	The verification has exceeded the attempt limit
`VERIFICATION_EXPIRED`	400	The verification has expired

Get Started

Voice

Web Callback

WhatsApp

Reference

Authentication & tiers

Create a verification

The verdict — fail closed

Check the code

The result webhook

Poll status

One code per number, code expiry & idempotency

Rate limits & abuse controls

Errors

​Authentication & tiers

​Create a verification

​The verdict — fail closed

​Check the code

​The result webhook

​Poll status

​One code per number, code expiry & idempotency

​Rate limits & abuse controls

​Errors

Authentication & tiers

Create a verification

The verdict — fail closed

Check the code

The result webhook

Poll status

One code per number, code expiry & idempotency

Rate limits & abuse controls

Errors