Skip to content

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}}.
send-code.ts
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******4567
console.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.

check-code.ts
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.

get-verification.ts
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.

list-verifications.ts
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);

Every verification that matches, following cursors.

approval-rate.ts
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`);

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.

verify-settings.ts
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');

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.

update-verify-settings.ts
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