Verify phone numbers
Verify sends a one-time code (OTP) to a phone number and checks the code the user types back. SMSFabric generates the code, sends it from your phones, and never returns or stores it: only a keyed hash is kept and compared in constant time. You don’t have to build code storage, expiry or attempt counting yourself.
The flow
Section titled “The flow”- Your backend calls
POST /v1/verificationswith the user’s number. You get back a verificationidwithstatus: "pending". - The user receives an SMS such as
Your verification code is 482913. It expires in 10 minutes. Never share it with anyone. - The user types the code into your app, and your backend calls
POST /v1/verifications/:id/check. status: "approved"means the code matched. Anything else means it did not.
The key needs verify:send to send and verify:check to check. Never call Verify from a browser or mobile app: the key would be exposed. Call it from your backend.
Send a code
Section titled “Send a code”curl https://api.smsfabric.com/v1/verifications \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: signup-usr_8812-otp-1" \ -d '{"to": "+201001234567", "channel": "sms", "locale": "ar"}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const verification = await sf.verifications.send( { to: '+201001234567', locale: 'ar' }, { idempotencyKey: 'signup-usr_8812-otp-1' },);// Keep verification.id with the user's session. The code never comes back.console.log(verification.id, verification.status, verification.expiresAt);import osimport requests
res = requests.post( "https://api.smsfabric.com/v1/verifications", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"], "Idempotency-Key": "signup-usr_8812-otp-1"}, json={"to": "+201001234567", "channel": "sms", "locale": "ar"}, timeout=30,)res.raise_for_status()verification = res.json()print(verification["id"], verification["status"])<?php$ch = curl_init('https://api.smsfabric.com/v1/verifications');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['to' => '+201001234567', 'channel' => 'sms', 'locale' => 'ar']), CURLOPT_HTTPHEADER => [ 'X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json', 'Idempotency-Key: signup-usr_8812-otp-1', ], CURLOPT_RETURNTRANSFER => true,]);$verification = json_decode(curl_exec($ch), true);echo $verification['id'] . ' ' . $verification['status'] . "\n";{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "to": "+20******4567", "status": "pending", "channel": "sms", "locale": "ar", "expiresAt": "2026-11-19T12:10:00.000Z", "attempts": 0, "maxAttempts": 5, "createdAt": "2026-11-19T12:00:00.000Z", "updatedAt": "2026-11-19T12:00:00.000Z"}to is always masked: the country calling code and the last 4 digits.
| Field | Default | Range |
|---|---|---|
to |
E.164 number. Required. | |
channel |
sms. Required in the raw API; the SDK fills it in. |
|
locale |
en |
en or ar, the language of the default text. |
codeLength |
6 | 4 to 10 digits. |
ttlSeconds |
600 | 60 to 1,800 seconds. |
template |
Your own text, up to 320 characters. It must contain {{code}} and may use {{minutes}}. |
Sending again to the same number cancels the earlier pending verification (status: "canceled"), so only the newest code works.
The SMS itself is an ordinary message with metadata.verificationId. Every API view of it, webhooks included, shows body: "[verification code hidden]": only the recipient’s phone sees the code.
Check the code
Section titled “Check the code”curl https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"code": "482913"}'import { SMSFabric } from '@smsfabric/sdk';
const sf = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const result = await sf.verifications.check('ver_k3j2h1g0f9e8d7c6b5a4z3y2', '482913');if (result.status === 'approved') { // Mark the number as verified.} else if (result.status === 'pending') { console.log(`Wrong code. ${result.attemptsLeft} attempts left.`);} else { console.log(`Verification is ${result.status}. Send a new code.`);}import osimport requests
res = requests.post( "https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check", headers={"X-Api-Key": os.environ["SMSFABRIC_API_KEY"]}, json={"code": "482913"}, timeout=30,)res.raise_for_status()result = res.json()print(result["status"], result["attemptsLeft"])<?php$ch = curl_init('https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2/check');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode(['code' => '482913']), CURLOPT_HTTPHEADER => ['X-Api-Key: ' . getenv('SMSFABRIC_API_KEY'), 'Content-Type: application/json'], CURLOPT_RETURNTRANSFER => true,]);$result = json_decode(curl_exec($ch), true);echo $result['status'] . ' ' . $result['attemptsLeft'] . "\n";{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "status": "pending", "attemptsLeft": 4 }status |
Meaning | What to tell the user |
|---|---|---|
approved |
The code matched. | Continue. |
pending |
Wrong code; attemptsLeft tries remain. |
“That code is wrong. Try again.” |
denied |
The 5th wrong code. Closed. | Offer to send a new code. |
expired |
The TTL passed. Closed. | Offer to send a new code. |
canceled |
A newer code was sent to the number. Closed. | Ask for the newest code. |
Every check that compares a code uses one attempt. A closed verification returns its status without comparing. Checking an approved verification again returns 409 verification_already_approved, so a code can’t be used twice.
The SDK never retries a check automatically, because each one counts as an attempt.
SMS-pumping protection
Section titled “SMS-pumping protection”Fraudsters trigger OTPs to premium or expensive number ranges and earn a share of the charge. Verify refuses those sends before any SMS leaves your phones. The rules run in this order:
| Rule | Default | Refusal |
|---|---|---|
| Blacklisted number | 422 verify_recipient_blacklisted |
|
| Country not allowed. Until you save a list, the allowed countries are the ones your SIM numbers are in. Non-geographic numbers (+800, +870, +881…) are never allowed. | Your SIMs’ countries | 403 verify_country_not_allowed |
| The number’s range (the number without its last 4 digits) is blocked | 403 verify_prefix_blocked |
|
| Codes to one number | 3 per 10 minutes | 429 verify_resend_limited + Retry-After |
| Codes to one country | 150 per hour | 429 verify_velocity_exceeded + Retry-After |
| Codes for the organization | 300 per hour | 429 verify_velocity_exceeded + Retry-After |
| Distinct numbers in one range within 10 minutes | 10 | 403 verify_prefix_blocked, and the range is blocked |
Change the allowed countries and the hourly limits under Settings → Verify in the portal (walkthrough). Only a signed-in user can change them: PUT /v1/verify/settings with an API key returns 403 api_key_not_allowed, so a leaked key cannot open new countries. Read the current settings with GET /v1/verify/settings.
A refusal other than the per-number limit writes verify.blocked to your audit log and sends a verification.blocked webhook. A blocked range stays blocked until SMSFabric support releases it.
Webhooks
Section titled “Webhooks”| Event | When |
|---|---|
verification.approved |
A check matched. data is the verification. |
verification.expired |
A pending verification reached its TTL. |
verification.blocked |
A send was refused by pumping protection. data.reason is country_not_allowed, prefix_blocked, prefix_burst, country_velocity or org_velocity. |
Test in the sandbox
Section titled “Test in the sandbox”With an sf_test_ key, sends, limits and checks behave as in live mode, but no SMS leaves a phone. Because the code is never returned, you can test wrong-code, expiry and limit handling in the sandbox, and test approval with a live key on your own number.