WhatsApp Verification API Integration Guide

Phone-Verif verifies a phone number with Reverse OTP: instead of sending a code to the user and asking them to type it back, you show them a WhatsApp deep link or QR code. They send one pre-filled message from their own WhatsApp account, your webhook fires, and you receive the number WhatsApp has already verified. Nothing secret travels to the user, so there is no code to intercept, phish, or inflate with artificially inflated traffic.

The whole integration is two REST calls against https://api.phone-verif.com. You can run the flow yourself in the demo before writing any code.

Every call is authenticated with an API key from your API keys page. Send it in the x-api-key header. The key query parameter is accepted too, but it ends up in logs and referrers — use it for debugging only, never from a browser.

x-api-key: {API_KEY}

POST /start-verification creates a session. All three body fields are optional: session_id is generated when you omit it, callback_url is where the user is sent once verified, and is_public controls whether reading the session status requires your API key.

curl -X POST https://api.phone-verif.com/start-verification \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "order-4821", "callback_url": "https://your-app.example/verified"}'

The response carries the session, the WhatsApp number and deep link to present, and the hosted web URL if you would rather redirect than build your own screen:

{
  "session_id": "order-4821",
  "validation_token": "…",
  "status": "pending",
  "whatsapp": { "number": "…", "deeplink": "https://wa.me/…?text=…" },
  "links": { "web": "https://phone-verif.com/verify?…" },
  "session": { "status": "pending", "validity_timestamp": 0, "created_at": "…" }
}

Render whatsapp.deeplink as a QR code on desktop and as a button on mobile, where tapping it opens WhatsApp with the message already written.

GET /check-verification-status takes the session_id or the token returned above and reports where the session is:

curl "https://api.phone-verif.com/check-verification-status?session_id=order-4821" \
  -H "x-api-key: $API_KEY"

{
  "session_id": "order-4821",
  "status": "verified",
  "validated_phone_number": "+33…",
  "session": { "verified_at": "…", "opened_at": "…", "previewed_at": "…" }
}

status moves through pending → whatsapp_previewed → opened → verified, or ends at expired. validated_phone_number is null until the session reaches verified, so treat that status as the only signal — never the presence of the field.

In production, rely on the callback rather than a polling loop. Poll check-verification-status during development, or on an explicit user action such as returning to the tab.

Errors come back as a JSON body with error, message, code and http_code. A 400 means a missing API key or parameter, 403 that the key has hit its usage limit or cannot read that session, 404 that the key or session does not exist, and 500 a server-side failure worth retrying.

For users without WhatsApp, the verification page falls back to SMS: the same token is sent as a plain text message instead. The Reverse OTP integration guide walks through detection and fallback in detail, and WhatsApp usage by country shows where that fallback actually matters.

Verifications are billed as prepaid credits — see Phone-Verif pricing.