Your own codes or our verification API: which way to send SMS codes from your system

The short answer: there are two ways. In the first, your system creates the code, stores it hashed, counts the attempts and sends us only the finished text with POST /v1/sms/messages. In the second, you use our verification API, POST /v1/sms/otp, and we do all of that for you. For confirming numbers, logins and payments, the second is simpler and harder to get wrong. The first is for when you need something the verification API does not do.

Side by side

	Your own codes (/v1/sms/messages)	Verification API (/v1/sms/otp)
Who creates the code	Your system	We do, with a random code
Where it is stored	In your database (it should be the hash only)	With us, hash only; your system keeps the id
Validity and attempts	You have to build them	The expires_in and max_attempts fields, with defaults
Code format	Anything you like	Digits only, 4 to 8
Text	Free, up to 1,600 characters	Yours, up to 300 characters, with {code} once
When it goes out	In your account's normal queue	Ahead of your account's other messages
Sandbox tests	Simulates the send	Simulates the send and returns the code, so you can test the check
Cost	The SMS credits	The SMS credits; checking costs nothing

When to choose the verification API

1	Confirming that the number belongs to the customer, at sign-up or when they change number.

2	Adding a second step to logins on your website or app, without asking anyone to install anything.

3	Approving a transaction: a payment, a withdrawal, a delivery. One code per transaction, with a short validity.

4	When you would rather not keep codes in your database. Less data stored, less data to lose.

When your own codes make sense

If the code must contain letters, if it has to stay valid for more than 60 minutes (at that point it is a temporary password rather than a verification code), or if your system already has all the logic built and tested, you can keep sending the finished text through the SMS API. Then every security precaution is yours: they are in sending one-time codes safely, and the practical side in verification codes through the SMS API.

Do not mix the two ways for the same job. A code you created and sent as a normal message cannot be checked with /verify: the verification API only knows the codes it created itself.

One key works for both. Sending a message and sending or checking a verification code need the same permission, sms:write. Reading the status needs sms:read.

Would you rather we created, sent and checked the code? See Verification SMS.

See Verification SMS

Categories

Categories