post

/v1/verify/call

An API that delivers patented phone-based verification and two-factor authentication (2FA) using a one-time passcode (OTP) sent over voice message in the event the end-user chooses the voice method, provides a landline or is not authorized to receive SMS messages in a specific country. NOTE: If you try this API out using the API Explorer, you will be billed for the transaction as you normally would.

All requests submitted for the Voice Verify API:

  • Can be authenticated with Basic (easiest to implement) and Digest
  • Use https://rest-ww.telesign.com/v1/verify/call as the base endpoint
  • Accept only UTF-8 encoded unicode characters as inputs
  • Use Content-Type - application/x-www-form-urlencoded in request headers

Request Body

Form data (application/x-www-form-urlencoded)
phone_number
string

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

required
ucid
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)
originating_ip
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.

language
string

A code specifying the language of the predefined template you wish to use. For a complete list of codes, see the section Supported Languages.

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

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

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

caller_id
string

This parameter allows you to set a phone number as caller ID for a Voice API message 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. Learn how to buy a number to use as caller id in the Buy a Phone Number (Caller ID) section of this page.

tts_message
string

Provides a custom text-to-speech (TTS) message containing the verify code to play to the end user, to be used by the service instead of one of TeleSign’s predefined templates. If your message is not in US English, specify its language in the language parameter. The default template is “Hello. Thank you for using our phone verification system. Your code is {code}. Once again, your code is {code}. Goodbye.” If you are having TeleSign generate your code, include the variable $$CODE$$ in the message text. For a list of languages supported for TTS, see the section Supported Languages. For tips relating to creating TTS messages, see the section Text-to-Speech Hints.

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

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

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

Your request was fulfilled and resulted in a new resource being created. If you want to code against a response, you should retrieve the status or error code and use that rather than the HTTP status response.

Status Code Associated Text String Description
100 Call answered The call was answered.
101 Not answered The call was not answered.
103 Call in progress TeleSign is either making the call or playing the voice message.
105 Call not handled yet The verification call has not yet been attempted.
106 Call failed An error occurred. No further attempt to call will be made.
107 Line busy The line is busy.
108 Call canceled by TeleSign Call canceled by TeleSign.
129 Call blocked by your request TeleSign blocked the call before it was placed. This is due to your prior submitted request to blocklist this phone number.
130 Call blocked by TeleSign TeleSign blocked the phone call. This can happen if the message contains inappropriate material, or if TeleSign believes the client is abusing the service.
500 Transaction not No Call, SMS, or PhoneID request was attempted.
501 Not authorized No permissions for this resource, or authorization failed.
599 Status not available The system is unable to provide status at this time.
Schema
object
reference_id
string

A 32-digit hex value that identifies your web service request. This value is unique for each web service request, is randomly-generated by TeleSign, and is returned in the response message immediately following your initial POST request.

sub_resource
string

The subresource to access; it is set to call.

errors
object

A JSON object that contains information on error conditions that might have resulted from the request, in an array of property-value pairs. If multiple errors occur, a pair is returned for each error.

status
object

An object that indicates the current state/progress of the web service call. This status pertains to the technical aspects of delivering the verification code to your end users via a phone call. For example, The call was not answered. This object contains the following keys -

verify
object

An object that indicates the verification result. This object contains the following key-

voice
object

An object that contains the following -

call_fowarding
object

Specifies the action that you want TeleSign to perform if the phone number has Call Forwarding enabled. This object contains the following keys -

numbering
object

Appears when you enable Score. An object containing details about the numbering attributes of the specified phone number.

phone_type
object

Appears when you enable Score.

risk
object

Appears when you enable Score. An object that describes the risk score for the phone number specified in the request

Send a Test Request

Send requests directly from the browser (CORS must be enabled)
$$.env
1 variable not set
host