Sign in

v1

latestOpenAPI 3.0.02026-07-2491237338.9 KB
Verify

Start a verification

Starts a verification by sending an SMS, voice, or email message to the recipient. This verification is charged once the message is sent successfully.

post/verify/verifications

Request body

channel'sms' | 'voice' | 'email_code' | 'whatsapp' required

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.
tostring 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.
codestring

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

senderIdstring

Sender ID to be used.

signaturestring

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.

languagestring

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

externalIdstring

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.

Example request

{
  "channel": "sms",
  "to": "+16315551111",
  "code": "123456",
  "senderId": "Brand",
  "signature": "Brand",
  "language": "en"
}

Response

The request is successfully accepted.

idstring required

ID of the verification.

status'pending' | 'approved' | 'blocked' | 'expired' | 'undelivered'

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.
tostring

Recipient of the verification.

channel'sms' | 'voice' | 'email_code' | 'whatsapp'

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.
sendTimestring date-time

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

totalPricenumber double

Total price of this verification.

currencystring

Price currency. ISO 4217 currency code.

smsFallbackEnabledboolean

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.

externalIdstring

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.

Example response

{
  "id": "ve6j7n8i",
  "to": "+16315551111",
  "channel": "sms",
  "sendTime": "2022-06-01T12:00:00.000Z",
  "totalPrice": 0.0085,
  "currency": "USD",
  "smsFallback": {
    "unsupportedReason": "SENDER_ID_UNAVAILABLE",
    "unsupportedDetail": "This Sender ID is not registered."
  }
}