Confirming a phone number at sign-up with an SMS code, step by step

WhatsApp & APIs·· 104 views· 4 min read

The short answer: at sign-up, ask for the number, send a code with POST /v1/sms/otp and only mark the number as confirmed when POST /v1/sms/otp/{id}/verify answers valid: true. That way you know the phone really belongs to the person signing up, not to a neighbour, a competitor or a bot. The number can be written with or without the country code, because the system can tell the country from the first digit: 841234567 goes to Mozambique and 923456789 to Angola. So +258 84 123 4567 and 258841234567 are the same number as 841234567.

The flow, step by step

1 The form asks for the number along with the other details. Before sending a code, check in your own system that the form is not being driven by a bot (see fraud through your code form).
2 Your server sends the code with POST /v1/sms/otp and the Idempotency-Key header (one value per sign-up attempt). A double click on “Create account” returns the same response and does not send two SMS.
3 Keep the id in the sign-up session, never in the browser. It is what ties the code to that sign-up.
4 Show the code screen with the masked number the response gives in to and a “Not your number? Fix it” link.
5 Check what the customer typed with /verify. With valid: true, save the number as confirmed and the time, which comes in verified_at.
6 With valid: false, say how many attempts are left (attempts_left) and, if the status is no longer pending, offer a new code.

The fields that matter at sign-up

Field Suggested for sign-up Limits
number The number the customer typed, as it is Mobile numbers in Mozambique and Angola
length 6, the default: easy to type, hard to guess 4 to 8 digits
expires_in 5 to 10 minutes: the customer is right there, waiting 1 to 60 minutes
max_attempts 3 to 5 1 to 10
text Your service name, {code} and “Do not share it” Up to 300 characters
sender Your Sender ID, if you have one Approved for the number's country

Create the account before or after the code?

Both work. If you create the account straight away, keep it in a “number not confirmed” state and hold back anything that depends on the phone. If you create it only after the code, keep the form data in the session until valid: true. What you should never do is treat the number as confirmed just because the SMS went out.

Answer the same way whether or not an account exists for that number. A message such as “This number is already registered” tells anyone who your customers are. Prefer “If the number is valid, you will get a code” and deal with existing accounts after the code is confirmed.
Test the whole flow in the Sandbox before opening sign-up to the public: the send response includes the code, so you can try the right code, a wrong one and an expired one without using credits.

Want to confirm the number of everyone who signs up on your site or app? See Verification SMS.

See Verification SMS

SEE ALSO

SMS verification API: we generate, send and check the code, and your system keeps only the id

The code entry screen: the field, a countdown, attempts left and clear messages

SMS fraud through your code form: how credits get burnt and how to stop it

Changing a customer's phone number safely: confirm the new number before saving it

Testing SMS verification in the Sandbox: the code comes back in the response

What a Sender ID is: SMS that arrive with your company name instead of a number

RECOMMENDED PRODUCT

Web hosting with cPanel

Domain and SSL included, daily backups and the panel you already know. from ₦9.900,00/mo (3-year plan, with coupon)

See plans
Was this answer helpful? Your answer helps us improve this article.

Related Articles

WhatsApp & APIs 1,277 Putting WhatsApp on your site: the link, the button and the ready-written message In Mozambique, WhatsApp is where business conversations happen. A contact form gives you a message somebody reads tomorr...
WhatsApp & APIs 1,157 Ordinary WhatsApp, Business or the Cloud API: which suits your business We call four different things «WhatsApp», and choosing the wrong one costs money or costs the number. One is free and is...
WhatsApp & APIs 1,306 WhatsApp for business: the risks, and the practices that avoid them WhatsApp has become the sales channel for many businesses in Mozambique, and that brought a risk few weigh up: the numbe...
WhatsApp & APIs 1,239 WhatsApp, e-mail or SMS: advantages, disadvantages, risks and who each is for WhatsApp, e-mail and SMS all exist to talk to customers, and the question «which is best» has no answer - because they a...
WhatsApp & APIs 1,054 Ordinary WhatsApp for business: advantages, disadvantages, risks and who it is for The app almost everyone starts with - the same one used personally - put to work for the business. It is the commonest o...
WhatsApp & APIs 59 Confirming payments, withdrawals and transfers with an SMS code: one code per operation The short answer: before approving a payment, a withdrawal or a transfer, send a code to the customer's phone and only c...