Send a voice verification code

Use this action to send a voice message with a one-time passcode (OTP) to a recipient phone number.

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

General requirements

  • Authentication: Basic (easiest to implement) and Digest
  • Encoding: Accepts only UTF-8 encoded unicode characters as inputs
  • Accepts: application/x-www-form-urlencoded
  • Required headers: Content-Type - application/x-www-form-urlencoded
  • Rate limit: Default rate limits by product
Log in to see full request history
Form Data
string
required

The end user's phone number, as a string of digits without spaces or punctuation, beginning with the country dialing code (for example, "1" for North America).

string

A string specifying a use case code. Choices include -

  • ATCK - for use in a 2FA situation like updating an account or logging in
  • BACF - for creating an account where the service may be vulnerable to bulk attacks and fraudsters
  • BACS - for creating an account where the service may be vulnerable to bulk attacks or individual spammers
  • CHBK - for use when someone is trying to buy something expensive or unusual and you want to verify it is really them
  • CLDR - calendar event
  • LEAD - for use in a situation where you require a person to enter personal information in order to obtain information about something like a loan or realty or school, and you want to check if the person is bogus or not
  • OTHR - if you have a situation not addressed by other tags
  • PWRT - for use in a situation where a password reset is required
  • RESV - for use when you have end users making reservations and not showing up, and you want to be able to include phone verification in the loop
  • RXPF - for use when you are trying to prevent prescription fraud
  • SHIP - for use when you are sending a shipping notification
  • THEF - for use when you are trying to prevent an end user from deactivating or redirecting a phone number in order to take over someone else's identity
  • TRVF - for use when you are transferring money and you want to check to see if it is approved by sending a text message or phone call to your end user. This is similar to CHBK, but is specifically for a money transaction
  • UNKN - if you have a situation not addressed by other tags (same as OTHR)
string

Your end user's IP address (do not send your own IP address). IPv4 and IPv6 are supported. For IPv4, the value must be in the format defined by the Internet Engineering Task Force (IETF) in the Internet-Draft document titled Internet Protocol. For IPv6, the value must be in the format defined by the IETF in the Internet-Draft document titled IP Version 6 Addressing Architecture.

string
Defaults to en-US

A code specifying the language of the predefined template you wish to use. For a complete list of codes, see Voice Verify API - Supported languages for audio templates. If you also include the tts_message parameter in this request, a different set of language codes is supported by the service; for a complete list of those codes, see Voice - Supported languages for text-to-speech. If the language you want to use is not supported, you may be able to add a custom audio template to your account, contact our Customer Support Team for more details.

string

By default, the verification code used for the code challenge is a randomly generated five-digit number assigned by Telesign. If you prefer to use your own verification code, you can override the default behavior by including a three- to five-digit numeric value between 100 and 99999 as the value for this parameter.

string

This message is to be used in conjunction with prompt_digit. You provide a message to play, it is converted to text-to-speech and sent in a call and played for the end user. You are limited to 2000 code points. The message should contain the digit you want to press. For example, you might have the message - Press 7 to continue. Make sure the digit in your message matches the digit you send for prompt_digit. If the end user presses the correct digit, then the message you have for the message parameter plays. If the end user does not press the correct digit, the follow up message does not play, they hear the regular message repeated again. This can happen up to three times. If an end user presses incorrect digits on the third play through, the call hangs up. If the end user does not press any digits in the allotted time, the message repeats. If the end user does not press any digits a second time in a row, the call hangs up. All messages use the same language tag if you choose to include one.

string

This digit is to be used in conjunction with prompt_message. Provide a single digit 0-9 that you want the end user to press. After playing the prompt message, the system will wait and give the end user two chances to press the correct digit. If they do, the message in the message parameter plays. All messages use the same language tag if you choose to include one.

string

This parameter allows you to set a phone number as caller ID for a Voice Verify API call sent to your end users. In order to use a specific caller ID, you must purchase a phone number from Telesign. This can be done by contacting our Customer Support Team and asking to buy one or more numbers. Be aware that 100% preservation of a caller ID value is not guaranteed. Telesign or a terminating operator may override the caller ID value that your end user will receive in order to improve delivery quality or follow local Telecom regulations in particular countries.

string

Provides a custom text-to-speech (TTS) message containing the verification one-time passcode (OTP) to play to the end user; this overrides the default template for the specified language. You must specify the message's language in the language parameter and the variable $$CODE$$ in the message text. See Voice Verify API - Text-to-speech tips for more details about this feature.

string

PressX is a feature that allows you to send an end user a message that asks them to press a digit in order to hear their verification code. The message is in English, and as follows: Hello. Thank you for using the phone verification system. Please press digit to hear your code. The digit is randomly selected by Telesign, and the end user gets two tries to get the correct digit. If the end user presses the correct digit, they will receive a message containing their verification code. Please note that this feature is only available in English, so you cannot use a language tag for other languages with it. To use this feature, you would put pressx=1 in the body of your request. You cannot use this feature with TTS.

string

It is not an issue when a user’s phone number belongs to a modern Private Branch Exchange (PBX) because outside numbers are usually assigned to individual extensions. Older PBX systems on the other hand, require extra call processing because incoming calls require either a live switchboard operator or an automated attendant to request the number of the user’s extension before completing the call. By default, Telesign does not support older PBX systems, but you can enable support for either live or automated switchboard scenarios by including the extension_type parameter. When you use this parameter, you must also use extension_template.

string

A numerical string that specifies the extension used in the call, as described above. If the user must be reached at an extension, then use this parameter to specify the extension number. The extension string is composed of digits. You may use a maximum of 28 characters to specify your extension. For the extension_type=1 (DTMF digits are dialed), you can include commas in the extension number string, where each comma represents a one second pause in the dialing sequence.

Responses

Response body
object
string

A unique, randomly generated hex value that identifies your web service request.

string

The sub-resource in the URI path from your original request to initiate this transaction. Indicates which form of verification you used.

errors
array of objects

Contains an object for each error condition that resulted from the request.

errors
object
integer

A numeric code specifying which error occurred.

string

Text describing the error that occurred.

status
object

Contains details about the request status.

integer
required

A numeric code indicating the processing status of this request.

string
required

A text description of the status code.

string
required

An RFC 3339 timestamp indicating when the request status was updated.

verify
object

Contains properties about the status of the verification attempt by the end user (if any).

string
required

Indicates whether the verification code you provided in your request matches that sent by Telesign to the end-user. Possible values are:

  • VALID - The codes match.
  • INVALID - The codes do not match.
  • EXPIRED - The match was attempted after the end of the validity period for the code.
  • MAX_ATTEMPTS_EXCEEDED - The match was attempted after the end user already had made the maximum allowed number of attempts for the code.
  • UNKNOWN - Any other state.

VALID INVALID UNKNOWN EXPIRED MAX_ATTEMPTS_EXCEEDED

string
required

If the end user entered a code, what they entered is provided here.

voice
object
string

The sender ID used for the call.

Language
Credentials
: