Signup Verification API

Signup verification is a check placed inside registration that requires a new account to be attached to a phone number its owner can prove they hold. It is the cheapest identity signal available at the exact moment you know least about a user, and the only one they cannot generate in bulk for free.

The distinction that matters is between collecting a number and verifying one. A registration form that merely stores whatever was typed has a contact field. A form that verifies it has a constraint — and constraints are what abuse economics run on.

Automated signups are the obvious case: a script can mint email addresses indefinitely, but each verified phone number costs a real SIM or a real WhatsApp account. That single fact turns a free attack into a priced one.

The subtler cases are worth more. Referral and welcome-bonus programmes are only as sound as their definition of a distinct person, and an unverified email address is not one. Neither is a disposable inbox behind a trial. Verification at signup is what stops the same individual claiming a first-time offer fifty times.

Put verification as early as it can carry its weight and no earlier. Verifying before a user has seen any value is the most common way to lose them; verifying after they have created content or spent money means dealing with an account you now have to unwind.

A reasonable default is to verify at the end of registration, after the account exists but before it can act — post, transact, invite, or claim anything. If your product has a genuinely useful anonymous mode, defer verification until the first action that has a cost to you.

Every added step loses some users, and that is a real cost, not one to argue away. What you can control is how much friction the step carries. A conventional code flow asks the user to leave your page, find a message, read a code, come back and type it — four opportunities to give up, plus a carrier delivery wait that may or may not resolve.

A Reverse OTP flow replaces all of that with one tap and one send. The user never leaves for long, never transcribes anything, and never waits for delivery to a device they are already holding. The check is the same; the number of ways to fail it is much smaller.

Open a session with POST /start-verification when the user reaches the verification step, passing your own identifier as the session_id so the result maps straight back to the pending account. Render the returned WhatsApp deep link as a QR code on desktop or a button on mobile.

Then wait for the callback, or read GET /check-verification-status when the user returns to the tab. Only mark the account verified when the status is verified — and store the number the API returns, not the one the user typed, since they are allowed to differ.

Sessions expire, so make restarting one a visible, unremarkable action rather than an error state. Users without WhatsApp need the SMS fallback presented clearly instead of as a hidden last resort. And shared or recycled numbers exist: decide deliberately whether a number may be attached to more than one account, because the default you pick silently becomes policy.

Finally, treat verification as reusable. Once a number is proved at signup, the same proof can back account recovery and later step-up checks without asking the user to enrol anything new.