Skip to content

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.

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.
POST/v1/verificationsverify:send

Generates 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}}.
Terminal window
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.
POST/v1/verifications/:id/checkverify:check

Compares 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.
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": "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.
GET/v1/verifications/:idverify:check

Returns the verification. A pending verification past its expiresAt is returned as expired.

Terminal window
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"
}
GET/v1/verificationsverify:check

Newest first, paginated.

Query Type Description
status string One verification status.
limit integer 1 to 200, default 50.
cursor string nextCursor from the previous page.
Terminal window
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/v1/verify/settingsverify:check

Returns the allowed countries and the protection limits in force.

Terminal window
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.

PUT/v1/verify/settingssettings:manageuser token only

Replaces 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.
Terminal window
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.