Verifications
sms.verifications is Verify: SMSFabric generates a one-time code, sends it through your phones and checks what the user types. The code never comes back from the API; only the recipient sees it. Sending needs the verify:send scope, everything else needs verify:check. The full flow is in Verify.
| Method | HTTP | Returns |
|---|---|---|
send(params, options?) |
POST /v1/verifications |
Verification |
check(id, code) |
POST /v1/verifications/:id/check |
VerificationCheck |
get(id) |
GET /v1/verifications/:id |
Verification |
list(params?) |
GET /v1/verifications |
Paginated<Verification> |
listAll(params?) |
GET /v1/verifications (every page) |
AsyncGenerator<Verification> |
settings.get() |
GET /v1/verify/settings |
VerifySettings |
settings.update(params) |
PUT /v1/verify/settings |
VerifySettings |
Sends a code to one E.164 number. A new send to a number that has a pending code cancels the old one.
| Parameter | Type | Notes |
|---|---|---|
to |
string |
E.164 recipient. |
channel |
'sms' |
Default and only value: sms. |
locale |
'en' | 'ar' |
Language of the default text. Default en. |
codeLength |
number |
4 to 10 digits. Default 6. |
ttlSeconds |
number |
60 to 1,800. Default 600. |
template |
string |
Your own text, up to 320 characters. Must contain {{code}}; may use {{minutes}}. |
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const verification = await sms.verifications.send({ to: '+201001234567', locale: 'ar', codeLength: 6, ttlSeconds: 300,});
// Keep the id with the sign-in attempt; `to` comes back masked: +20******4567console.log(verification.id, verification.to, verification.expiresAt);Network errors and 5xx are retried with the same idempotency key. A 429 is not retried: verify_resend_limited (3 codes per number every 10 minutes) and verify_velocity_exceeded carry a Retry-After in seconds that you should show the user; the SDK puts it on the error as err.retryAfter (see Errors). Other refusals are 403 verify_country_not_allowed, 403 verify_prefix_blocked and 422 verify_recipient_blacklisted; see SMS-pumping protection.
Checks the code the user typed. The result’s status is:
status |
Meaning |
|---|---|
approved |
The code matched. The number is verified. |
pending |
Wrong code. attemptsLeft more tries remain. |
denied |
The 5th wrong code. Send a new one. |
expired |
The TTL passed. Send a new one. |
canceled |
A newer code replaced this one. |
A verification that is already approved returns 409 verification_already_approved. check is never retried automatically, because every check that evaluates a code uses one attempt.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const result = await sms.verifications.check('ver_…', '482913');
if (result.status === 'approved') console.log('Verified');else if (result.status === 'pending') console.log(`Wrong code, ${result.attemptsLeft} tries left`);else console.log(`Code ${result.status}: send a new one`);One verification, with attempts, maxAttempts and the masked number.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const v = await sms.verifications.get('ver_…');console.log(v.status, `${v.attempts}/${v.maxAttempts}`, v.expiresAt);One page of verifications, newest first. Filter by status; page with limit and cursor.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const page = await sms.verifications.list({ status: 'denied', limit: 20 });for (const v of page.data) console.log(v.createdAt, v.to);listAll
Section titled “listAll”Every verification that matches, following cursors.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
let total = 0;let approved = 0;for await (const v of sms.verifications.listAll({ limit: 200 })) { total += 1; if (v.status === 'approved') approved += 1;}console.log(`${approved} of ${total} approved`);settings.get
Section titled “settings.get”The SMS-pumping protection in force: the countries codes may go to (allowedCountries), whether that list was saved by you (configured) or derived from your SIM numbers (sim_numbers), each limit and the number of active range blocks. Needs verify:check.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ apiKey: process.env.SMSFABRIC_API_KEY });
const settings = await sms.verifications.settings.get();console.log(settings.allowedCountries, settings.source);console.log('Per number:', settings.limits.perNumber.limit, 'per', settings.limits.perNumber.windowSeconds, 's');settings.update
Section titled “settings.update”Replaces the allowed countries and, optionally, the limits: orgHourlyLimit and countryHourlyLimit (1 to 1,000 sends per hour) and prefixBurstThreshold (3 to 50 distinct numbers in one range within 10 minutes). An empty allowedCountries list sends nowhere.
import { SMSFabric } from '@smsfabric/sdk';
const sms = new SMSFabric({ accessToken: process.env.SMSFABRIC_ACCESS_TOKEN });
const settings = await sms.verifications.settings.update({ allowedCountries: ['EG', 'SA', 'AE'], countryHourlyLimit: 100,});console.log(settings.source); // configured