Skip to main content
POST

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Verification request that needs to be sent.

​
channel
enum<string>
required

The channel through which the verification code will be sent. Supported channels are sms (text message), voice (phone call), email_code (email), and whatsapp (WhatsApp message).

Available options:
sms,
voice,
email_code,
whatsapp
Example:

"sms"

​
to
string
required

The recipient's phone number or email address depending on channel.

  • Phone number: In E.164 format. Applicable when channel is sms or voice.
  • Email address: For example, tom@example.com. Applicable when channel is email_code.
Example:

"+16315551111"

​
code
string

Verification code to be sent. This field is optional. If not provided, we will automatically generate a code.

Required string length: 4 - 8
Example:

"123456"

​
senderId
string

Sender ID to be used.

Example:

"Brand"

​
signature
string

This parameter is only required for Chinese mainland SMS messages. You must specify an approved signature such as Brand. It will be added to the beginning of SMS body and wrapped with 【】, e.g. 【Brand】Your verification code is 123456.

Example:

"Brand"

​
language
string

ISO 639 Language Code. If not specified, language will be set as en by default. Notably, in certain countries or regions, language will be automatically set as the local language due to the regional restrictions. Applicable languages: ar: Arabic de: German en: English es: Spanish fr: French id: Indonesian it: Italian pt_BR: Portuguese ru: Russian tr: Turkish vi: Vietnamese zh_CN: Simplified Chinese zh_HK: Traditional Chinese

Example:

"en"

​
externalId
string

A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems. If present, this value will also be attached to the externalId of message objects.

Response

200 - application/json

The request is successfully accepted.

​
id
string
required

ID of the verification.

Example:

"ve6j7n8i"

​
status
enum<string>

Status of the verification.

  • pending: The verification message (SMS, Voice, etc.) is sent, waiting to be checked. This happens when you call the 'Start a verification' API successfully.
  • approved: The verification has been successfully checked. A pending verification status changes to approved when you call the 'Check a verification' API and receive a response with the valid parameter is true. An approved verification cannot be checked anymore.
  • blocked: The verification is blocked by user-defined rules such as denylist, and geographical permission restrictions. A blocked verification cannot be checked.
  • expired: The verification has expired and cannot be checked anymore.
  • undelivered: Our system has received a delivery receipt indicating that the verification message was not delivered. An undelivered verification cannot be checked anymore.
Available options:
pending,
approved,
blocked,
expired,
undelivered
​
to
string

Recipient of the verification.

Example:

"+16315551111"

​
channel
enum<string>

Supports several independent channels for verification:

  • sms: Sends an SMS message with a verification code.
  • voice: Makes a voice call with a verification code.
  • email_code: Sends an email with a verification code.
  • whatsapp: Sends a WhatsApp message with a verification code.
Available options:
sms,
voice,
email_code,
whatsapp
Example:

"sms"

​
sendTime
string<date-time>

The time at which this verification was sent, formatted in RFC 3339. e.g., 2022-06-01T12:00:00.000Z.

Example:

"2022-06-01T12:00:00.000Z"

​
totalPrice
number<double>

Total price of this verification.

Example:

0.0085

​
currency
string

Price currency. ISO 4217 currency code.

Example:

"USD"

​
smsFallbackEnabled
boolean

Whether sms fallback is enabled or not. Applicable when channel is whatsapp. If enabled, we will try to send the verification code via sms when the WhatsApp message is failed.

​
smsFallback
object

Included when smsFallbackEnabled is true.

​
externalId
string

A unique (recommended) string to reference the object. This can be an order number or similar, and can be used to reconcile the object with your internal systems.