Verifications
A verification is one one-time code sent to one number. The code is never returned, logged or stored in clear text. See Verify phone numbers for the flow.
The verification object
Section titled “The verification object”| Field | Type | Description |
|---|---|---|
id |
string | ver_… |
to |
string | The number, masked: calling code and last 4 digits (+20******4567). |
status |
string | pending, approved, denied, expired or canceled. |
channel |
string | sms. |
locale |
string | en or ar. |
expiresAt |
string | When the code stops working. |
attempts |
integer | Checks that compared a code. |
maxAttempts |
integer | 5. |
createdAt, updatedAt |
string | Timestamps. |
Send a code
Section titled “Send a code”/v1/verificationsverify:sendGenerates a code and sends it by SMS through your phones. Returns 201 with the verification. Supports Idempotency-Key. A pending verification for the same number is canceled.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
to |
string | Yes | Recipient. | E.164. |
channel |
string | Yes | Delivery channel. | sms. |
locale |
string | No | Language of the default text. | en (default) or ar. |
codeLength |
integer | No | Digits in the code. | 4 to 10, default 6. |
ttlSeconds |
integer | No | Lifetime of the code. | 60 to 1,800, default 600. |
template |
string | No | Your own text. | Up to 320 characters; must contain {{code}}; may use {{minutes}}. |
curl https://api.smsfabric.com/v1/verifications \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: login-usr_8812-1732014000" \ -d '{"to": "+201001234567", "channel": "sms", "codeLength": 6, "template": "Acme: your login code is {{code}}. It expires in {{minutes}} minutes."}'{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "to": "+20******4567", "status": "pending", "channel": "sms", "locale": "en", "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"}| Error | When |
|---|---|
400 validation_failed |
Invalid number, out-of-range field, or a template without {{code}}. |
422 verify_recipient_blacklisted |
The number is on your blacklist. |
403 verify_country_not_allowed |
The number’s country is not allowed. |
403 verify_prefix_blocked |
The number’s range is blocked. |
429 verify_resend_limited |
3 codes to this number in 10 minutes. Retry-After gives the wait in seconds. |
429 verify_velocity_exceeded |
Hourly limit for the country or the organization reached. Retry-After given. |
Check a code
Section titled “Check a code”/v1/verifications/:id/checkverify:checkCompares the code the user typed. Returns 200. Every check that compares a code uses one attempt; a closed verification returns its status without comparing.
| Path | Type | Description |
|---|---|---|
id |
string | The verification id. |
| Body field | Type | Required | Constraints |
|---|---|---|---|
code |
string | Yes | 4 to 10 digits. |
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": "approved", "attemptsLeft": 0 }status is approved on a match, pending with attemptsLeft on a wrong code, denied on the 5th wrong code, and expired after the TTL. attemptsLeft is 0 unless the verification is still pending.
| Error | When |
|---|---|
409 verification_already_approved |
The verification was already approved. |
404 not_found |
No such verification in your organization. |
Retrieve a verification
Section titled “Retrieve a verification”/v1/verifications/:idverify:checkReturns the verification. A pending verification past its expiresAt is returned as expired.
curl https://api.smsfabric.com/v1/verifications/ver_k3j2h1g0f9e8d7c6b5a4z3y2 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "id": "ver_k3j2h1g0f9e8d7c6b5a4z3y2", "to": "+20******4567", "status": "approved", "channel": "sms", "locale": "en", "expiresAt": "2026-11-19T12:10:00.000Z", "attempts": 1, "maxAttempts": 5, "createdAt": "2026-11-19T12:00:00.000Z", "updatedAt": "2026-11-19T12:01:12.480Z"}List verifications
Section titled “List verifications”/v1/verificationsverify:checkNewest first, paginated.
| Query | Type | Description |
|---|---|---|
status |
string | One verification status. |
limit |
integer | 1 to 200, default 50. |
cursor |
string | nextCursor from the previous page. |
curl "https://api.smsfabric.com/v1/verifications?status=pending" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "ver_l4k3j2h1g0f9e8d7c6b5a4z3", "to": "+966*****4567", "status": "pending", "channel": "sms", "locale": "ar", "expiresAt": "2026-11-19T12:20:00.000Z", "attempts": 1, "maxAttempts": 5, "createdAt": "2026-11-19T12:10:00.000Z", "updatedAt": "2026-11-19T12:11:04.003Z" } ], "nextCursor": null}Get Verify settings
Section titled “Get Verify settings”/v1/verify/settingsverify:checkReturns the allowed countries and the protection limits in force.
curl https://api.smsfabric.com/v1/verify/settings \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "allowedCountries": ["EG", "SA"], "source": "sim_numbers", "limits": { "perNumber": { "limit": 3, "windowSeconds": 600 }, "perCountry": { "limit": 150, "windowSeconds": 3600 }, "perOrg": { "limit": 300, "windowSeconds": 3600 }, "prefixBurst": { "limit": 10, "windowSeconds": 600 }, "maxAttempts": 5 }, "activeBlocks": 0}source is sim_numbers while you haven’t saved a list (the allowed countries are those of your SIM numbers) and configured after you have.
Update Verify settings
Section titled “Update Verify settings”/v1/verify/settingssettings:manageuser token onlyReplaces the allowed countries and, optionally, the limits. Signed-in users only, so a leaked API key can’t open new countries. Audited as verify.settings_updated. Returns the same shape as the GET.
| Body field | Type | Required | Constraints |
|---|---|---|---|
allowedCountries |
string[] | Yes | ISO 3166-1 alpha-2 codes. An empty list sends nowhere. |
orgHourlyLimit |
integer | No | 1 to 1,000. Default 300. |
countryHourlyLimit |
integer | No | 1 to 1,000. Default 150. |
prefixBurstThreshold |
integer | No | 3 to 50. Default 10. |
curl -X PUT https://api.smsfabric.com/v1/verify/settings \ -H "Authorization: Bearer $SMSFABRIC_USER_TOKEN" \ -H "Content-Type: application/json" \ -d '{"allowedCountries": ["EG", "SA", "AE"], "countryHourlyLimit": 200}'| Error | When |
|---|---|
403 api_key_not_allowed |
Called with an API key. |