Use case
Verification code texts
Send sign-in and verification codes to UK mobiles through the REST API. Your application creates and checks each code; CaptiFi Connect delivers it as an ordinary text and tells you what happened to it.
Does CaptiFi Connect send verification codes?
Yes, as ordinary texts through the API. Your application generates the code, stores it and checks what the user types, and CaptiFi Connect delivers the text to a UK mobile and reports its status by webhook. CaptiFi Connect doesn't generate, store or check codes itself, so there's no separate verification product to set up.
How it fits together
A code flow has two halves. Your application handles the security side: it generates a random code, stores a hash of it with an expiry time, limits how many attempts and resends a user gets, and checks the code they type in. CaptiFi Connect handles delivery: it takes the text, sends it to the user's UK mobile and reports whether it arrived.
Because the checking happens in your application, you decide the expiry, the number of attempts and how codes fit into your sign-in, and none of that changes if you ever send codes another way.
Sending a code through the API
When a user asks for a code, your application calls POST /api/v1/messages with their number and the text. Send each request with an Idempotency-Key that's unique to that code, so a retry after a network timeout can't send the same code twice.
Leave out the sender name to send from a UK mobile number, or use an approved sender name so users can see at a glance that the code is from you. Subscribe to message.failed, and if a code text fails, your application can offer another way to verify straight away.
If the number is refused, because it's a landline, an overseas mobile or a number that's opted out of your texts, the API response says so with a reason before anything is charged, so you can tell the user there and then.
Writing the code text
Short and plain works best:
- Put the code near the start and say what it's for.
- Say how long it lasts.
- Tell people never to share it, and that you'll never ask for it.
- Leave links out. People are rightly wary of texts with a code and a link in them.
- Stick to plain characters so the text stays in one part.
Features you'll use
The parts of CaptiFi Connect a code flow uses:
- POST /api/v1/messages with Bearer API keys.
- The Idempotency-Key header for safe retries.
- Webhooks for message.sent, message.delivered and message.failed, signed with HMAC SHA-256.
- Test keys, which simulate delivery so you can build the flow without texting anyone.
- Approved sender names, if you want the code to show your brand.
Rules and limits
A code someone asked for is a service message, so the marketing rules don't apply. Keep it that way and leave offers out of code texts.
Codes go to UK mobiles only, including Guernsey, Jersey and the Isle of Man. If some of your users have overseas numbers, they'll need another way to verify. An opted-out number gets nothing either: if a user once texted STOP to you, CaptiFi Connect refuses their code with the reason opted_out until they text START, so your sign-in screen should explain what to do.
Test keys never send to a phone, so you can't receive a test code on your handset. Use them to build the flow and the webhook handling, then try a live key with your own number once your account is approved.
Text codes make a reasonable second factor, but they can be intercepted, for example through SIM swap fraud. For accounts holding money or sensitive data, offer an authenticator app as well.
Who sends codes by text
Apps and websites with a sign-in, booking platforms confirming a phone number before a first booking, marketplaces checking new sellers, and any business confirming a change to someone's account details.
Sample texts
Merge fields in braces are filled from each contact. The part count is worked out the way the platform bills it.
Sign-in code(service)
Your Brightwell sign-in code is 482913. It expires in 10 minutes. Never share this code. We will never ask you for it.
118 characters, 1 part
Confirming a mobile number(service)
731054 is your Fernside Pets code to confirm your mobile number. It expires in 15 minutes.
90 characters, 1 part
Change of account details(service)
Use code 590382 to confirm the change to your Northside Gym account. If you didn't ask for this, call us on 01632 960456.
121 characters, 1 part
Set up code texts through the API
- 1
Create a test key
In the dashboard, create a test key. It works before your account is approved and costs nothing.
- 2
Generate and store the code
In your application, create a random code, store a hash with an expiry, and limit attempts and resends.
- 3
Send the text
Call POST /api/v1/messages with the number, the code text and an Idempotency-Key.
- 4
Handle the webhook
Check the signature, then act on message.failed by offering another way to verify.
- 5
Go live
Once your account is approved and has credit, switch to a live key and send a code to your own phone.
Questions people ask
Does CaptiFi Connect generate or check the codes?
No. Your application creates the code, stores it and checks it. CaptiFi Connect sends the text and reports whether it was delivered.
Can I test code texts without sending real ones?
Yes. Test keys accept the same requests as live keys, simulate delivery, send the sent and delivered webhooks and charge nothing. They're limited to 50 numbers a request and 300 numbers an hour.
Can I send codes to overseas numbers?
No. CaptiFi Connect sends to UK mobiles only. Other numbers are refused with a reason and not charged, so you'll need another method for those users.
What happens if the user has opted out?
The API refuses the text with the reason opted_out and doesn't charge for it. The user can text START to opt back in.
Should the code come from a sender name?
It can. An approved sender name shows your brand, and nobody can reply to it, which suits code texts. Request one in the dashboard; staff check it, including against the MEF SenderID Protection Registry, before you can use it.
What does each code cost?
One credit per SMS part, and a typical code text fits in one part. Packs start at £25 for 500 credits (5p a text) and fall to 3.5p on the biggest pack, plus VAT; the pricing page has the table.
Send your first text this week
Set up your account and contacts now; we check every new account before it can send.