Skip to content

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.

  1. Your backend calls POST /v1/verifications with the user’s number. You get back a verification id with status: "pending".
  2. The user receives an SMS such as Your verification code is 482913. It expires in 10 minutes. Never share it with anyone.
  3. The user types the code into your app, and your backend calls POST /v1/verifications/:id/check.
  4. 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.

Terminal window
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"}'
{
"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.

Terminal window
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"}'
{ "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.

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.

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.

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.