Skip to main content
POST
Send a verification code

Authorizations

Authorization
string
header
required

Dashboard JWT token from Clerk

Body

application/json
to
string
required

Recipient (E.164 phone or email)

channel
enum<string>

Delivery channel for the OTP (defaults to sms)

Available options:
sms,
whatsapp,
email,
viber,
voice,
telegram,
silent,
rcs,
flashcall,
sna,
totp,
push,
magic_link,
backup_code
channels
enum<string>[]

Optional ad-hoc fallback channel chain (overlays the send when no profile_id is set)

Required array length: 1 - 4 elements
Available options:
sms,
whatsapp,
email,
voice,
viber,
telegram,
silent,
rcs
fallback_config
object

Optional async fallback engine config (pairs with channels)

max_attempts
integer
default:3

Max verification attempts

Required range: 1 <= x <= 10
profile_id
string

Optional verification profile ID. Format is vprof_<hex> (per generateId("vprof")); NOT a bare UUID — the prior format: uuid constraint here was the root cause of DEVOTEL-ORBIT-28 (27 events in 11 days) where every FE call with a real profile id 422'd before reaching the Zod parse.

Required string length: 1 - 64
country
string

Optional ISO 3166-1 alpha-2 country hint (e.g. TR) so national-format phone numbers normalise to the E.164 form OTP providers require. Not needed for clean E.164 input.

Required string length: 2
code_length
integer
default:6

Number of digits in the generated OTP (defaults to 6). Must equal custom_code length when a custom code is supplied.

Required range: 4 <= x <= 8
sca_binding
object

Optional PSD2 SCA dynamic-linking binding. Replay the SAME object on POST /verify/check; a mismatch rejects with BINDING_MISMATCH. Omit for non-PSD2 flows.

locale
enum<string>

Optional 2-letter language code selecting the localized voice TTS and SMS body for the built-in fallback message. Profile-defined templates override it. Region tags (e.g. es-MX) are rejected — use es.

Available options:
en,
es,
fr,
de,
it,
pt,
nl,
tr,
ar,
ja,
zh,
ko,
ru,
pl,
sv,
da,
nb,
fi,
cs,
el,
he,
hi,
id,
th,
vi
custom_code
string

Optional caller-supplied OTP (4–8 digits, digits only) for sandbox / test-mode QA. Rejected on live keys. Its length must equal code_length.

Pattern: ^\d{4,8}$
device_token
string

Device-bound network access token for the sna channel (Silent Network Authentication), obtained via the GSMA Open Gateway / CAMARA flow. When present on an sna send, verification completes via a network possession-proof and no OTP is minted.

Minimum string length: 1

Response

Verification code sent

Verification code sent

data
object
meta
object