Phone Verification API

Phone verification is the act of proving that the person in front of you actually controls the phone number they typed in. A number on a form is a claim; verification turns it into evidence. Without it, a signup field accepts typos, disposable numbers, other people's numbers and whatever a script decides to paste in.

That evidence is worth having for three separate reasons. It gives you a contact channel that works, so password resets and delivery notifications reach a real handset. It gives you a stable identifier for an account, which is what makes multi-accounting and bonus abuse expensive. And it gives you a second factor you can fall back on later, without asking the user to enrol anything new.

Every phone verification flow rests on the same idea: something has to happen on the handset that only its holder could cause. The classic version sends a one-time code by SMS and asks the user to type it back. Phone-Verif runs it the other way round — the user sends a message instead of receiving one — but the shape is the same: create a session, present a challenge, wait for proof, read the result.

In practice that means three moving parts on your side. A call that opens a verification session and gives you something to show the user. A screen or widget where they act on it. And a way to learn the outcome, either from a callback or by reading the session's status.

WhatsApp is the primary channel here. The API returns a WhatsApp deep link containing a short session token; you render it as a QR code on desktop or a button on mobile. The user taps it, WhatsApp opens with the message already written, and they send it. WhatsApp reports the sending number to the server, and because WhatsApp verified that number when the account was created, you inherit a proof you did not have to build.

How much of your traffic this covers depends entirely on the market. WhatsApp usage is close to universal in Brazil, India and much of Europe and Africa, and marginal in the United States, Japan and South Korea. It is worth checking where your users actually are before deciding how much fallback you need.

For users without WhatsApp, the same session accepts the same token over SMS: the user sends the token as a plain text message to the verification number instead. The session, the token and the status you read afterwards are identical, so your integration does not branch — only the instruction shown to the user changes.

That matters more than it sounds. A WhatsApp-only flow silently loses everyone in low-adoption markets; an SMS-only flow pays a carrier for every attempt, including the ones a bot triggers. Keeping both on one session lets you default to the cheap, secure channel and still reach the rest.

In a conventional OTP flow the server sends a secret and hopes it arrives at the right handset and nowhere else. That assumption is what SIM swap attacks and OTP phishing both exploit, and it is what makes artificially inflated traffic profitable: every attempt costs you a message whether or not a real user is behind it.

Reverse OTP removes the assumption. Nothing secret is sent to the user, so there is nothing to intercept, nothing to phish out of them, and no outbound message for a fraudster to bill you for. The user's own act of sending is the proof.

A session starts in a pending state. It moves through whatsapp_previewed when the user sees the pre-filled message, opened when they open the link, and verified once the message arrives and is matched back to the session. If nobody acts in time, it ends at expired instead.

Only the verified state carries the phone number; until then the field is null. Treat the status as the signal and the number as its payload, never the other way round — that one rule removes most of the race conditions people hit when they first integrate.

The integration is two REST calls. POST /start-verification opens a session and returns the WhatsApp number, the deep link and a hosted web URL if you would rather redirect than build your own screen. GET /check-verification-status returns the session's state and, once verified, the number itself.

You can skip the UI entirely and embed the hosted verification page in an iframe, which is the fastest route to something working. Either way, prefer the callback over a polling loop in production, and poll only during development or when the user explicitly returns to your page.

Sessions are short-lived and each token is bound to exactly one of them, so a replayed message matches nothing. The number you receive comes from WhatsApp's own infrastructure rather than from user input, which closes the gap where a user can simply type someone else's number and wait for a code they intercepted.

On the privacy side, the flow moves less personal data than the one it replaces: no code travels through a telecom network on its way to the user, and you store the verified number rather than a trail of delivery attempts.

Verifications are billed as prepaid credits. There is no subscription and credits do not expire, so a seasonal signup spike costs what it costs and a quiet month costs nothing. New accounts start with free credits, which is enough to run the flow end to end in a staging environment before committing to anything.