Initiate verification
POST https://verify.8x8.com/api/v2/subaccounts/:subAccountId/sessions
This method allows you to:
- Generate and send a message containing a one-time password
- Place a Voice call containing a one-time password
- Initiate Silent Mobile Authentication (SMA) verification
Request
Path Parameters
Possible values: >= 3 characters and <= 50 characters, Value must match regular expression ^[A-Za-z0-9\-._&]{3,50}$
You must replace {subAccountId} with the subaccountid that you want to use. By default this is generated once you signed up with a new account at https://connect.8x8.com.
Body
- The destination phone number to be verified.
- The destination can be provided in 2 formats:
- National format: a phone number without the international dialing prefix. When using this format, the country parameter must be provided. Without it, 8x8 cannot determine the country of origin and the request cannot be routed.
-
International format: a phone number including the international dialing prefix, for example 65 for Singapore. The number may be provided with or without a leading
+. Any leading 0 after the country code must be removed.
- All non-relevant formatting characters such as spaces, brackets, and dashes are automatically removed. You may safely provide unformatted user input.
- Required when the destination phone number is provided in national format.
- Must contain the ISO Alpha-2 country code of the destination number.
- When provided, 8x8 automatically formats the number for international routing by adding the country dialing prefix and removing any leading 0 if present.
- If omitted for a national format number, the request cannot be routed to the mobile network operator.
- It designates which channel should be used to send the verify request.
- The default value is
sms - If used, the brand parameter can be inserted as a placeholder in the text of the message defined in the template object. The brand could be inserted in plain-text in the text but using placeholders allows you to maintain a single request method while enabling Verify request across a wide range of products or brands.
- It designates the length the code that will be generated and inserted in your message.
- The value should be greater or equal to 3 and less or equal to 10.
- The default value is
4 - It designates the expiry period after which the generated code will not be valid for verification anymore.
- This value represents seconds.
- The value should be greater or equal to 30 and less or equal to 7200.
- The default value is
300 - It can be set to the following standard modes:
-
NUMERIC- regex: ^[0-9]{3,10}$)
- example: 123456
-
NUMERIC_WITH_DASH- regex ==> ^[0-9-]{3,10}$)
- example: 234-3294 or 231-461
- remarks:
- if codeLength == 3 then no dash sign will be used (=NUMERIC)
- only one dash will be used in the code and located at the center of the code or moved one character to the left of the center of the code if the code cannot be split into 2 halves of digits of same length (see example)
-
ALPHANUMERIC- regex ==> ^[a-zA-Z0-9]{3,10}$)
- example: fiQdAsr315
-
ALPHANUMERIC_CAPITALS- regex ==> ^[A-Z0-9]{3,10}$)
- example: FIQDASR315
-
ALPHANUMERIC_EASY- (regex: ^((?![IOQSZ])[A-Z0-9]){3,10}$)
- example: FDAR315
- remark: same as ALPHANUMERIC_CAPITALS but excluding I, O, Q, S and Z
-
- It is only used for
smsandcallchannels. - It defines the content of your message, it can be customized for each request using the placeholders
{code}and{brand}. - NB: if personalizing the text of the template, make sure to include the
{code}placeholder or your Verify SMS/CALL will not contain any code. The same goes with the{brand}placeholder, if not provided but used in the template, it will be empty. -
Default text (if no value is provided):
- If brand is specified:
{brand}: Your verification code is {code}
- If brand is not specified:
Your verification code is {code}
- If brand is specified:
-
For
callchannel- It designates the language of voice to read the text to the end user.
-
The language should be provided if the template value specified for
callchannel. - The default value is
en-US
-
For
whatsappchannel- It designates the language of template to be used.
- If not provided, the default value is the first available language of the requested template.
-
Possible case-sensitive values are:
- ar-EG
- ar-SA
- bg-BG
- ca-ES
- cs-CZ
- da-DK
- de-AT
- de-CH
- de-DE
- el-GR
- en-AU
- en-CA
- en-GB
- en-IE
- en-IN
- en-US
- es-ES
- es-MX
- fi-FI
- fr-CA
- fr-CH
- fr-FR
- he-IL
- hi-IN
- hr-HR
- hu-HU
- id-ID
- it-IT
- ja-JP
- ko-KR
- ms-MY
- nb-NO
- nl-NL
- pl-PL
- pt-BR
- pt-PT
- ro-RO
- ru-RU
- sk-SK
- sl-SI
- sv-SE
- ta-IN
- th-TH
- tr-TR
- vi-VN
- zh-CN
- zh-HK
- zh-TW
- This value defines the API behavior when it comes to code generation in the case of multiple requests sent to the same destination during the period of validity of a code sent previously.
- If the value is set to true: a new code will be generated and the verification request will be reinitialized. Be aware that it can lead to some confusion if the 2 SMS reach the destination device at the same time.
- If the value is set to false: as long as the verification is still in pending state, the same code will be re-sent and the validity will be extended.
- The default behavior (if the parameter is left empty) is to keep existing session with same OTP.
- It defines the API behavior when it comes to multiple requests to send a code to the same destination phone number during the validity time of a verification process.
- This value represents seconds.
- If the value is specified, the system will compare the timing of the current request with the last one for the same destination number. If the time difference between the two is less then resending interval, the OTP request will not be re-sent to the customer and the API will throw a 403 (forbidden) error.
- The value should be greater or equal to 10 and less or equal to 7200.
- The default value is
10 - It defines the Webhook URL where status of verification attempts will be posted.
- This object is not mandatory
-
This object is taken into account only when the
channelproperty is set tosms - The source value can also be called senderID or TPOA.
- It is the "from" address that will be used when delivering the SMS to the handset.
- It can take different formats:
- Alphanumeric (example: MyBrand): this is the case when a source is composed of an alphanumeric string (max 11 characters: letters from the ASCII character set, digits, and the space character). Alphanumeric sources are generally used for branded SMS to help the SMS receiver to identify the brand or services which originated the SMS.
- Numeric (example: +6512345678): this the case when a source is composed of a string made purely of digits (max 16 chars). It can also start with the + sign. Numeric sources are generally used when the originator intends to receive an answer to the SMS as it is interpreted as a regular phone number by the destination handset.
- NB - Limitations: According to the country where the SMS is sent to, sources can be overwritten in order to ensure a better delivery. If you have some specific inquiries related to the type of source available for your account towards a specific destination, please contact your account manager.
- The default value is
SMS - The defaults encoding value is
AUTO. - This parameter defines the character set to use for this SMS among the following:
- AUTO: the API will analyze the content of your SMS text and select the correct encoding according to the characters used: if your SMS text contains UNICODE characters, then UNICODE will be selected, otherwise it will be ASCII
- GSM7: by using GSM7, you are forcing the encoding in use to be GSM 7 bit: it will render correctly any of the characters from the character set (See a complete list there).
- UCS2: by using UCS2, you are forcing the encoding in use to be UCS2 encoding: it will render correctly any of the characters from the UNICODE character set (See a complete list there).
- This object is not mandatory
-
This object is taken into account only when the
channelproperty is set tocall - It designates your CallerID (caller).
- It designates the speed of speech in the resulting message.
- Accepted values range from
0.5to2, as a two digit number. - The default value is
0.8. - It designated the amount of times to repeat the text content.
- Accepted values are
1,2or3. - The default value is
2 - It designates the voice, gender and accent for the message you are sending.
- All available voice profiles can be found at https://developer.8x8.com/connect/reference/vm-voice-languages-and-profiles.
- The default value will be chosen based on the language parameter value.
-
This object is mandatory and is only taken into account when the
channelproperty is set towhatsapp - It designates the name of the WhatsApp Authentication Template to be used.
- For OTP-based channels, this value is used to apply rate limiting based on the client IP address.
- For the SMA channel, this value may be used to immediately validate the request when the IP address belongs to a supported mobile network gateway.
- If the request is forwarded by one or more proxies, you should extract the original client IP from the X-Forwarded-For header and provide it in this field.
- Refer to IP Spoofing for additional details.
This parameter is mandatory.
+1 (987) 654-3210
Optional parameter.
Possible values: <= 2 characters
US
This parameter is not mandatory.
Possible values: [sms, call, whatsapp, viber, sma]
sms
This parameter is not mandatory.
Possible values: <= 30 characters
This parameter is not mandatory.
Possible values: >= 3 and <= 10
4
This parameter is not mandatory.
Possible values: >= 30 and <= 7200
300
This parameter is not mandatory
Possible values: [NUMERIC, NUMERIC_WITH_DASH, ALPHANUMERIC, ALPHANUMERIC_CAPITALS, ALPHANUMERIC_EASY]
NUMERIC
This parameter is not mandatory.
This parameter is not mandatory.
en-US
This parameter is not mandatory.
This parameter is not mandatory.
Possible values: >= 10 and <= 7200
10
This parameter is not mandatory.
http://example.com
sms object
SMS channel-specific settings in Mobile Verification.
This parameter is not mandatory.
SMS
This parameter is not mandatory.
AUTO - GSM7 - UCS2
Possible values: [AUTO, GSM7, UCS2]
AUTO
call object
Call channel-specific settings in Mobile Verification.
This parameter is not mandatory.
+6598765432
This parameter is not mandatory.
Possible values: >= 0.5 and <= 2
0.8
This parameter is not mandatory.
Possible values: >= 1 and <= 3
2
This parameter is not mandatory.
Possible values: <= 50 characters
whatsapp object
WhatsApp channel-specific settings in Mobile Verification.
This parameter is mandatory.
Optional parameter.
The response returned is the following:
Schema
- WAITING (intermediary): it means that the verify request did not reach its expiry time and the API did not receive a token yet.
- VERIFIED (final): it means that the last token has been successfully checked against the mobile verification request within the validity time.
- FAILED (final): it means that the token verification has failed: the API accepts up to 5 attempts to provide the right code, if the fifth tentative is unsuccessful, the status is set to FAILED and cannot be reversed.
- EXPIRED (final): it means that the verification request reached its expiry time without receiving a token matching the one originally generated.
Unique id associated with the verification request.
It should used to verify the status of a request or check a code sent back by a user.
If several codes are generated for the same request, the sessionId will remain the same.
This is the prefix and the path to the verify request, it allows you to locate it easily.
Destination phone number to which the verification code was sent in international format (containing the international dialing prefix).
The current status of the verify request.
It can take the following values:
Possible values: [WAITING, VERIFIED, FAILED, EXPIRED]
Shows the count of unsuccessful attempts to verify a code for the current mobile verification request.
Possible values: >= 0 and <= 255
0
Shows the time at which the mobile verification request will expire.
Indicates how long the user should wait before resending the verification request for current session.
sma object
SMA channel-specific response object.
URL to be invoked in the background of client's mobile device to verify phone number via mobile data network.
{
"sessionId":"18b526ad-d063-48c0-bb93-4e71f042f047",
"verifyUri":"https://verify.8x8.com/api/v2/subaccounts/demo-account-123/sessions/18b526add06348c0bb934e71f042f047",
"destination":"6598765432",
"status":"WAITING",
"attempt":0,
"expiresAt":"2025-12-18T14:05:00.1254323+00:00",
"retryAfter":"2025-12-18T14:00:20.1254323+00:00"
}
{
"sessionId":"a44a91be5ea5ea118169020897df5459",
"verifyUri":"/api/v2/subaccounts/demo-account-123/sessions/a44a91be5ea5ea118169020897df5459",
"destination":"+198765432",
"status":"WAITING",
"attempt":0,
"expiresAt":"2025-12-18T05:59:54.09Z",
"retryAfter":"2025-12-18T05:55:04.09Z"
}
{
"sessionId":"a44a91be5ea5ea118169020897df5459",
"verifyUri":"/api/v2/subaccounts/demo-account-123/sessions/a44a91be5ea5ea118169020897df5459",
"destination":"+198765432",
"status":"WAITING",
"attempt":0,
"expiresAt":"2025-06-03T05:59:54.09Z",
"retryAfter":"2025-06-03T05:55:04.09Z",
"sma":{
"verificationUrl":"https://verify.8x8.com/sma/a44a91be5ea5ea118169020897df5459"
}
}
Bad request error response
Schema
Error code
Error description
Unique id of error. You can use it as reference when sending enquiries to 8x8 support
Date and time of the error occurrence
{
"code":1001,
"message":"Provided subAccountId doesn't belong to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2025-12-18T10:31:19.4297387+00:00"
}
{
"code":1001,
"message":"Provided subAccountId doesn't belong to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2025-12-18T02:31:19.4297387+00:00"
}
{
"code":1002,
"message":"Invalid MSISDN format (not E.164 international number)",
"errorId":"b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp":"2025-12-18T09:25:40.9235752+00:00"
}
Request was not authenticated response
Schema
Error code
Error description
Unique id of error. You can use it as reference when sending enquiries to 8x8 support
Date and time of the error occurrence
{
"code":1001,
"message":"Provided subAccountId doesn't belong to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2025-12-18T10:31:19.4297387+00:00"
}
{
"code":1200,
"message":"Request was not authenticated properly",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2025-12-18T09:42:38.8988997+00:00"
}
Upgrade Required — client is using an unsupported TLS version
Response Headers
TLS/1.3
Schema
Error code
Error description
Unique id of error. You can use it as reference when sending enquiries to 8x8 support
Date and time of the error occurrence
{
"code":1001,
"message":"Provided subAccountId doesn't belong to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2025-12-18T10:31:19.4297387+00:00"
}
{
"code":1014,
"message":"TLS 1.3+ is required for Singapore-bound messages. Detected: TLSv1.2",
"errorId":"b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp":"2025-12-18T09:25:40.9235752+00:00"
}
Internal server error
Schema
Error code
Error description
Unique id of error. You can use it as reference when sending enquiries to 8x8 support
Date and time of the error occurrence
{
"code":1001,
"message":"Provided subAccountId doesn't belong to your account",
"errorId":"91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp":"2025-12-18T10:31:19.4297387+00:00"
}
{
"code":2000,
"message":"Internal server error",
"errorId":"db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp":"2025-12-18T09:42:38.8988997+00:00"
}
Source: https://developer.8x8.com/connect/reference/verify-request-v-2 · 8x8 CPaaS Developer Docs. Synced for support deflection.
