Skip to content

WhatsApp Verification API

Verify a phone number with two REST calls and one message from the user. You show a link or QR code, the user sends a pre-filled WhatsApp message, and you receive the number WhatsApp already verified. There is no code to send, type, intercept or pump.

MarkdownOpenAPIllms.txt
  1. POST/start-verification200
  2. WAITuser sends one message0 codes
  3. HOOKverification_successverified

Quickstart

You need an API key. Create an account, finish onboarding for 100 free credits, then copy a key from API keys.

The base URL is https://api.phone-verif.com.

1. Start a session

Call POST /start-verification from your server. Send a unique session_id and the callback_url the user returns to.

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

Render whatsapp.deeplink as a QR code on desktop and as a button on mobile. The user opens WhatsApp, sends the pre-filled message and gets a confirmation with a link back to your callback_url.

200 OK (shortened)
{ "session": { "session_id": "order-4821", "validation_token": "xyz789", "status": "pending", "validity_timestamp": "2026-11-06T22:47:47.257Z" }, "whatsapp": { "number": "18073600555", "deeplink": "https://t.phone-verif.com/qr/xyz789" } }

3. Get the result

Add a webhook URL in Settings and verify its signature. We POST the result as soon as the message arrives.

Your own number can be verified without spending credits. Register it in your profile, then run the whole flow as many times as you need. To see the flow first, try the demo.

Webhook body
{ "event": "verification_success", "session_id": "order-4821", "validation_token": "xyz789", "status": "verified", "validated_phone_number": "33612345678", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10" }

How it works

The message travels from the user to us, so nothing secret is sent to them. There is no code to phish, and no outbound SMS for fraudsters to pump.

  1. Your server starts a session and receives a link containing a one-time token.
  2. The user opens the link on their phone or scans it, then sends the pre-filled message.
  3. WhatsApp delivers that message with the sender's number, which WhatsApp has already verified.
  4. We match the token to your session and send you the result.
  5. The user returns to your callback_url with ?token=<validation_token>.

A session stays valid for 10 hours. Credits are spent when a verification completes, not when it starts, so an abandoned session costs nothing.

Your server starts a session and shows a link. The user sends a message through WhatsApp, and Phone-Verif sends your server a signed webhook.Your serverPhone-VerifWhatsAppUserPOST /start-verificationlink and tokenshow QR code or buttonsends pre-filled messageverified sender numbersigned webhook

Authentication

Send your API key in the x-api-key header on every call.

The ?key= query parameter works too, but URLs end up in logs and browser history. Use it for debugging only.

Keys belong on your server. Anyone holding a key can spend your credits, so never ship one to a browser or a mobile app. Your frontend calls your backend, and your backend calls this API.

Header
x-api-key: YOUR_API_KEY

whatsapp.deeplink and whatsapp.qr_code_url go through our redirect, which records the scan and fills session.qr_code_scanned_at. whatsapp.direct_link opens WhatsApp directly and records nothing.

DeviceWhat to show
DesktopA QR code of whatsapp.qr_code_url
MobileA button that opens whatsapp.deeplink

Generate the QR code in your own frontend. Any QR library works, because the value is a plain URL.

React
import { QRCodeSVG } from 'qrcode.react'; export function VerifyPhone({ whatsapp }) { const isMobile = /Android|iPhone|iPad/.test(navigator.userAgent); return isMobile ? ( <a href={whatsapp.deeplink}>Verify with WhatsApp</a> ) : ( <QRCodeSVG value={whatsapp.qr_code_url} size={220} /> ); }

Handle the result

Use webhooks as your source of truth. They arrive within seconds, and they work when the user never returns to your app.

Poll only on an explicit action, such as the user coming back to your page. When they land on your callback_url, read token from the query string and ask your backend to check it.

The token in that URL proves nothing by itself. Always confirm the session from your server with GET /check-verification-status before you trust it.

Treat both verified and sms_validated as success. A session that has expired answers 410.

Your callback route (Express)
app.get('/verified', async (req, res) => { const url = new URL('https://api.phone-verif.com/check-verification-status'); url.searchParams.set('validation_token', req.query.token); const response = await fetch(url, { headers: { 'x-api-key': process.env.PHONE_VERIF_API_KEY }, }); if (!response.ok) return res.redirect('/verify?error=expired'); const { session } = await response.json(); const done = ['verified', 'sms_validated'].includes(session.status); res.redirect(done ? '/welcome' : '/verify?pending=1'); });

Verify webhook signatures

Every webhook carries an X-Webhook-Signature header: sha256= followed by the HMAC-SHA256 of the raw body, keyed with your webhook secret. Reject any request that fails the check.

  1. Fetch your secret once with GET /webhook-secret and store it as a server-side secret.
  2. Read the raw request body before any JSON parsing. Parsing and re-serializing changes the bytes.
  3. Compute the HMAC and compare it in constant time.

We retry once, after about 5 seconds, on a network error or a 5xx. Any other status counts as delivered, so answer 2xx quickly and do the work afterwards. A retry repeats the same event: use validation_token as your idempotency key. The age_verification_result event isn't retried.

Verify a webhook (Express)
import crypto from 'node:crypto'; import express from 'express'; const app = express(); app.post('/webhooks/phone-verif', express.raw({ type: 'application/json' }), (req, res) => { const expected = 'sha256=' + crypto .createHmac('sha256', process.env.PHONE_VERIF_WEBHOOK_SECRET) .update(req.body) .digest('hex'); const received = req.get('X-Webhook-Signature') ?? ''; const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected)); if (!valid) return res.sendStatus(401); const event = JSON.parse(req.body); res.sendStatus(200); handleEvent(event); // Idempotent: keyed on event.validation_token });

Login and 2FA

The flow parameter changes what a verification answers. Pass it in the query string or the JSON body of POST /start-verification.

flowUse it forYou receive
phone (default)Proving a numbervalidated_phone_number and user_id
loginPasswordless sign-inuser_id and is_new_user, no number
2faConfirming a known usermatch, no number
ageAge checksAn age block, no number and no user_id

user_id is a stable UUID for a given number and API key. Store it after the first verification. Unknown numbers on flow=login are registered automatically, with is_new_user: true.

flow=2fa requires user_id, which can be our UUID or your own linked ID. An unknown ID answers 404 before any session starts. If someone else replies, the session is still verified but match is false, so always check match.

login and 2fa hide the number by default. Add reveal=true to GET /check-verification-status to get it, for 1 credit on each call.

POST/start-verification
Webhook, flow=login
{ "event": "verification_success", "session_id": "order-4821", "status": "verified", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10", "is_new_user": false }
Start a 2FA check
curl -X POST https://api.phone-verif.com/start-verification \ -H "x-api-key: $PHONE_VERIF_API_KEY" \ -H "Content-Type: application/json" \ -d '{"flow": "2fa", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10"}'

Age verification

flow=age verifies the phone number, then confirms the person's age through our age provider. Your account must have age verification configured, otherwise the call answers 503.

min_age sets the threshold, and defaults to your configured value or 18. reset=1 ignores an earlier pass for that number and runs the age check again.

You receive two webhooks, both signed with the same secret: verification_success with age.status: "pending", then age_verification_result once the provider answers. age.status ends as verified, denied or failed. While it is pending, links.age_verification in the status response takes the user straight to it.

POST/start-verification
Start an age check
curl -X POST "https://api.phone-verif.com/start-verification?flow=age&min_age=18" \ -H "x-api-key: $PHONE_VERIF_API_KEY"
Webhook, age_verification_result
{ "event": "age_verification_result", "session_id": "order-4821", "validation_token": "xyz789", "status": "verified", "age": { "status": "verified", "verified": true, "required": 18, "verified_at": "2026-11-06T22:00:00.000Z", "provider": "ageverif" } }

Telegram

Every session is open to WhatsApp, SMS and our bot, @PhoneVerif_com_bot, unless you send provider. The response carries a whatsapp, an sms and a telegram block, all with the same token. Show the links you want, and the first channel the user completes wins.

For Telegram, show telegram.deeplink as a QR code or a button. The user presses Start, then shares their own number with one tap. Typed numbers and other people's contacts are refused.

session.provider reads any until a channel completes the session, then whatsapp or telegram. An SMS completion reads whatsapp, with the status sms_validated. The other channel then refuses the token.

To lock a session to one channel, send provider:

ValueBlocks returnedToken works on
any (default)whatsapp, sms, telegramAll three
whatsappwhatsapp, smsWhatsApp and SMS. session.provider is absent.
telegramtelegramThe bot

Webhooks and status checks carry provider. When Telegram completes a flow=phone session they also carry the Telegram account: at the top level of the webhook, and in session.telegram in the status response. username and last_name can be null.

  • validated_phone_number has the same format as on WhatsApp, so a number gets the same user_id on both channels.
  • With flow=age, the age link and result reach the user on the channel they finished on.
  • If Telegram is unavailable, the default opens a session without a telegram block, so check for it before showing it. provider=telegram answers 503 with TELEGRAM_UNAVAILABLE: fall back by calling again without provider.
Lock a session to Telegram
curl -X POST https://api.phone-verif.com/start-verification \ -H "x-api-key: $PHONE_VERIF_API_KEY" \ -H "Content-Type: application/json" \ -d '{"session_id": "order-4821", "provider": "telegram"}'
Response block
{ "telegram": { "bot_username": "PhoneVerif_com_bot", "deeplink": "https://t.phone-verif.com/tg/xyz789", "qr_code_url": "https://t.phone-verif.com/tg/xyz789", "direct_link": "https://t.me/PhoneVerif_com_bot?start=xyz789" } }
Webhook, flow=phone
{ "event": "verification_success", "session_id": "order-4821", "validation_token": "xyz789", "status": "verified", "validated_phone_number": "33612345678", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10", "provider": "telegram", "telegram": { "user_id": 123456789, "username": "alice", "first_name": "Alice", "last_name": "Martin" } }

Embed the hosted page

Skip building a screen: start the session on your server, then load our page in an iframe or webview. It handles the QR code, the button and the live status.

https://phone-verif.com/verify?session_id=SESSION_ID&token=VALIDATION_TOKEN&embedded=true

ParameterRequiredDescription
session_idYesThe ID you sent to /start-verification
tokenYessession.validation_token from the response
embeddedNotrue hides our header and footer

The page sends a verification_complete message to its parent. Check event.origin, and use the message only to move your interface on: browser code can be forged, so confirm the result from your server or your webhook.

Use https://phone-verif.com/demo?embedded=true while you develop. It spends no credits.

Embed
<iframe src="https://phone-verif.com/verify?session_id=SESSION_ID&token=TOKEN&embedded=true" width="100%" height="600" style="border: 0" title="Verify your phone number" ></iframe> <script> window.addEventListener('message', (event) => { if (event.origin !== 'https://phone-verif.com') return; if (event.data.type !== 'verification_complete') return; // Refresh from your backend, which confirms the session. location.reload(); }); </script>

Common mistakes

These are the errors that break an integration most often.

Don'tDo
Send api_key in the JSON body of /start-verificationUse the x-api-key header. The body field is ignored and the call answers 400.
Call the API from a browser or mobile appCall it from your server, and keep the key there.
Read status at the top level of a responseRead session.status. Session fields live under session.
Trust the token on your callback URL, or a postMessageConfirm with GET /check-verification-status or a signed webhook.
Wait for status: "expired"Handle 410: an expired session answers with an error.
Reuse a session_idGenerate a new one. Starting the same ID again cancels its previous token.
Expect +33612345678validated_phone_number has digits only: 33612345678.
Assume verified means the right person on flow=2faCheck match.
Parse the webhook before checking the signatureSign the raw bytes, then parse.

Go-live checklist

  • The API key is in a server-side secret, and appears in no client bundle.
  • callback_url is set for every session, or a default is set in Settings.
  • A webhook URL is set in Settings, and its signature is verified.
  • The webhook handler is idempotent and answers 2xx quickly.
  • 410 and 402 both show the user a way forward.
  • Your app alerts you before credits run out, using GET /credits.
  • You have run the flow end to end with your own number.

API overview

EndpointPurpose
POST /start-verificationStart a session
GET /check-verification-statusRead a session
POST /user-identityLink your own user ID
GET /user-identityLook up a linked ID
GET /webhook-secretGet your signing secret
GET /creditsRead your balance
GET /usageRead 12 months of usage

The full contract is in openapi.yaml. All bodies are JSON, and all timestamps are ISO 8601 in UTC.

POST/start-verification

Starts a session. Parameters go in the JSON body or the query string, and the query string wins.

ParameterTypeDescription
session_idstringYour ID, using letters, digits, - and _. Generated if omitted. Must be unique: reusing one cancels its previous token.
callback_urlstringWhere the user goes after verifying. Defaults to the URL in your Settings.
flowstringphone (default), login, 2fa or age.
providerstringany (default), whatsapp or telegram. any lets the user pick. The other two lock the session to that channel.
user_idstringRequired for flow=2fa. Our UUID or your linked ID.
min_ageintegerOnly for flow=age.
resetbooleanOnly for flow=age. Runs the age check again.

The sms block offers an SMS fallback for users without WhatsApp. Those sessions end with the status sms_validated.

Errors: 400 for invalid parameters or a missing key, 402 when credits run out, 404 for an unknown key or user_id, 503 when a provider isn't available.

POST/start-verification
200 OK
{ "session": { "session_id": "order-4821", "validation_token": "xyz789", "status": "pending", "validity_timestamp": "2026-11-06T22:47:47.257Z", "created_at": "2026-11-06T12:47:47.257Z", "qr_code_scanned_at": null, "previewed_at": null, "opened_at": null, "verified_at": null, "success_link_clicked_at": null, "whatsapp_message_sent_at": null, "whatsapp_message_received_at": null, "validated_phone_number": null }, "links": { "web": "https://your-app.example/verified?token=xyz789" }, "whatsapp": { "number": "18073600555", "deeplink": "https://t.phone-verif.com/qr/xyz789", "qr_code_url": "https://t.phone-verif.com/qr/xyz789", "direct_link": "https://wa.me/18073600555?text=Verification%20token%3A%20%5Bxyz789%5D" }, "sms": { "number": "18073600555", "qr_code_url": "sms:+18073600555?body=Verification%20token%3A%20%5Bxyz789%5D%20", "direct_link": "sms:+18073600555?body=Verification%20token%3A%20%5Bxyz789%5D%20" } }

GET/check-verification-status

Returns the same document as /start-verification, plus the fields of the session's flow. POST works too. You can only read sessions created with your own key.

ParameterTypeDescription
session_idstringThe session to read. Required without validation_token.
validation_tokenstringThe token from the session or callback URL.
revealbooleanAdds validated_phone_number on login and 2fa, for 1 credit per call.
FlowExtra fields under session once verified
phonevalidated_phone_number, user_id
loginuser_id, is_new_user, and external_id if linked
2famatch
ageage

session.status moves forward through these values:

StatusMeaning
pendingCreated, nothing has happened yet
qr_code_scannedThe QR code or deeplink was opened
whatsapp_previewedWhatsApp fetched the link preview
openedThe user opened the return link
verifiedVerified over WhatsApp or Telegram
sms_validatedVerified over SMS

Errors: 403 for a session that belongs to another key, 404 for an unknown session, 410 once it has expired.

GET/check-verification-status
Request
curl "https://api.phone-verif.com/check-verification-status?session_id=order-4821" \ -H "x-api-key: $PHONE_VERIF_API_KEY"
200 OK, verified (shortened)
{ "session": { "session_id": "order-4821", "validation_token": "xyz789", "status": "verified", "verified_at": "2026-11-06T12:49:32.801Z", "validated_phone_number": "33612345678", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10" }, "links": { "web": "https://your-app.example/verified?token=xyz789" } }

POST/user-identity

Links your own user ID to our user_id, so you can pass yours to flow=2fa. It spends no credits. Both fields are required.

ParameterTypeDescription
user_idstringOur UUID, from a verified session.
external_idstringYour ID for that user.
POST/user-identity
Request
curl -X POST https://api.phone-verif.com/user-identity \ -H "x-api-key: $PHONE_VERIF_API_KEY" \ -H "Content-Type: application/json" \ -d '{"user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10", "external_id": "customer_42"}'
200 OK
{ "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10", "external_id": "customer_42" }

GET/user-identity

Looks up a link from either side. Pass external_id or user_id in the query string. An unknown ID answers 404. It spends no credits.

GET/user-identity
Request
curl "https://api.phone-verif.com/user-identity?external_id=customer_42" \ -H "x-api-key: $PHONE_VERIF_API_KEY"

GET/webhook-secret

Returns the secret that signs your webhooks, and creates it on first use. See Verify webhook signatures.

GET/webhook-secret
Request
curl https://api.phone-verif.com/webhook-secret \ -H "x-api-key: $PHONE_VERIF_API_KEY"
200 OK
{ "webhook_secret": "6f1d…" }

GET/credits

Returns your balance. It answers 200 even at zero, so you can poll it for alerts. Read credits.remaining and credits.exhausted. credits.key.allowed is null when the key has no limit of its own.

GET/credits
Request
curl https://api.phone-verif.com/credits \ -H "x-api-key: $PHONE_VERIF_API_KEY"
200 OK
{ "top_up_url": "https://phone-verif.com/pricing", "api_key": { "key_prefix": "abc123", "name": "Production" }, "credits": { "remaining": 1250, "exhausted": false, "account": { "available": 1250 }, "key": { "used": 318, "allowed": null, "remaining": null, "uncapped": true } } }

GET/usage

Returns the last 12 months, newest first. Empty months are included with zero counts. It spends no credits.

billing spells out the quantities that are billed: monthly active users for login, yearly active users for 2fa. active_users_by_flow is null for months recorded before per-flow tracking.

GET/usage
Request
curl https://api.phone-verif.com/usage \ -H "x-api-key: $PHONE_VERIF_API_KEY"
200 OK (shortened)
{ "months": [ { "month": "2026-11", "active_users": 42, "active_users_by_flow": { "login": 28, "twofa": 15 }, "verifications": { "login": 28, "twofa": 15, "age": 0, "phone": 5 } } ], "years": [], "billing": { "login_monthly_active_users": [{ "month": "2026-11", "count": 28 }], "twofa_yearly_active_users": [{ "year": "2026", "count": 15 }] } }

Webhook events

We send a signed POST with Content-Type: application/json to the URL in your Settings.

EventWhenFlow-specific fields
verification_successThe message was matched to a sessionphone: validated_phone_number, user_id. login: user_id, is_new_user, external_id. 2fa: match. age: age.
age_verification_resultThe age provider answeredage

Every verification_success also has session_id, validation_token, status and the session timestamps. provider names the channel that completed the session, and is absent on a session locked to WhatsApp. When that channel is Telegram, flow=phone adds telegram.

verification_success, flow=phone
{ "event": "verification_success", "session_id": "order-4821", "validation_token": "xyz789", "status": "verified", "created_at": "2026-11-06T12:47:47.257Z", "qr_code_scanned_at": "2026-11-06T12:48:10.163Z", "previewed_at": null, "opened_at": null, "verified_at": "2026-11-06T12:49:32.801Z", "whatsapp_message_sent_at": "2026-11-06T12:49:33.102Z", "whatsapp_message_received_at": "2026-11-06T12:49:32.640Z", "validated_phone_number": "33612345678", "user_id": "5f0c9a52-8a3e-4a7e-9c1d-2b7d4f1e6a10" }

Errors

Errors use standard HTTP status codes and one JSON shape. Branch on the HTTP status, and show message only to developers. A 402 also carries developer_message, with the top-up link.

StatuserrorWhat to do
400API_KEY_REQUIREDSend the x-api-key header.
400API_KEY_VALIDATION_ERRORCheck the key. Don't retry.
400SESSION_ID_INVALIDUse only letters, digits, - and _.
400SESSION_ID_OR_TOKEN_REQUIREDSend session_id or validation_token.
400INVALID_VALIDATION_TOKENUnknown token: start a new session.
400INVALID_FLOW_PARAMETERFix flow, provider, user_id, min_age or reset. message names the problem.
400PHONE_NUMBER_INVALIDreveal needs a verified login or 2fa session.
402API_KEY_USAGE_LIMIT_EXCEEDEDOut of credits. Top up, then retry.
403ACCESS_FORBIDDENThis session belongs to another key. Don't retry.
404API_KEY_NOT_FOUNDUnknown API key. Don't retry.
404SESSION_NOT_FOUNDUnknown session.
404USER_NOT_FOUNDUnknown user_id or external_id.
410The session has expired. Start a new one and don't rely on error here.
500INTERNAL_SERVER_ERRORRetry with backoff.
502AGE_VERIFICATION_FAILEDThe age provider failed. Retry with backoff.
503AGE_VERIFICATION_UNAVAILABLEAge verification isn't configured for your account.
503TELEGRAM_UNAVAILABLECall again without provider.

Retry only 5xx responses and network errors. Back off between attempts, and stop after a few tries. POST /start-verification is safe to retry with the same session_id: the latest call's token is the valid one.

402 Payment Required
{ "error": "API_KEY_USAGE_LIMIT_EXCEEDED", "message": "The API key has reached its usage limit", "code": 1004, "http_code": 402, "developer_message": "No credits left on this account. Top up at https://phone-verif.com/pricing to resume verifications." }

Try the API

Send real requests from this page. Sign in and your key is filled in for you. Calls that complete a verification spend credits, unless you use your own registered number.

Endpoint
Flow
Provider

Your request and its response appear here.