Skip to main content

How the verification flows work

The overall shape is the same for every method: POST /v1/verify creates a session, and you learn the result either via a webhook or by polling GET /v1/verify/{request_id}. Only the middle differs — how the user completes verification.

Session statuses: sent → delivered (optional) → verified, or expired (TTL ran out) / failed (terminal error).

Which method to pick​

The question that decides everything else is whether you need a code input.

No code typedCode typed
reverse_flash_call — the user callssms · flash_call · pass_call
mts_id — confirmed on the SIM, but with a fallback to a codetelegram_otp · max_otp · max_bot

Which methods your account may use and what they cost — see Verification methods and pricing.

reverse_flash_call — no code typed​

The user calls a number we hand out, and we verify by caller id. Nobody types a code.

→ More on reverse_flash_call

sms — a code by SMS​

The code arrives by SMS; the user enters it on your side and you submit it for checking. The same "code → /v1/verify/check → verified" shape applies to every code-entry method below.

→ More on sms

flash_call — the code is in the incoming number​

We place a dropped call, and the code is the trailing code_length digits of the incoming number.

→ More on flash_call

pass_call — a robot dictates the code​

A robot calls and reads the code out. Unlike flash_call, this call has to be answered.

→ More on pass_call

telegram_otp — a code from Telegram​

The official Telegram bot delivers the code.

→ More on telegram_otp

max_otp — a code in the MAX messenger​

The message simply arrives — no links, no action from the user.

→ More on max_otp

max_bot — a code through a MAX bot​

The user opens the bot via deep_link and taps "Share number" — the code arrives only after that. Billing is charge-on-delivery.

→ More on max_bot

mts_id — operator-asserted​

Two paths, and you don't know in advance which fires: usually the operator confirms right on the SIM, but on failure it falls back to SMS-OTP. Don't show a code input up front — wait for the verification.code_required webhook or the awaiting_code: true flag.

→ More on mts_id

Learn the result: webhook or polling​

Both work, and you can combine them (webhook as primary, polling as a safety net):

  • Webhook — we push an event to your URL (see Webhooks).
  • Polling — periodically request GET /v1/verify/{request_id} until a terminal status.

The source of truth on any mismatch is GET /v1/verify/{request_id}.