Voice Verify API - Send a Voice Message with a Verification Code

The fastest way to send your first voice message request containing a verification code is to try out the Voice Verify API Explorer. If you have your credentials, follow the instructions to use TeleSign’s Voice Verify API for the first time. You will also be able to get a code snippet for the request in the language of your choice.

Use these instructions with the Voice Verify API Explorer to send a voice message containing a verification code (one-time password (OTP)) to the number you specify and get a code snippet for making the request in the language of your choice.

  1. Click the Auth [basic] tab.
  2. In the Username field, put your Customer ID.
  3. In the Password field, put your API key.
  4. Click the Body tab.
  5. In the phone_number field, enter your phone number. (See available parameters on the API reference page - POST /v1/verify/call.)
  6. Click Send.
  7. If you want the code for your request, so you can see how this request is implemented using basic authentication, click the Code Generation tab and use the Language and Library drop-downs to choose the language you want your code snippet in. The Language drop-down shows you what languages you can generate code in, and the Library drop-down shows you what libraries you could use to create the code.
  8. After you send your request, you will see the Body tab and a JSON response. Look through the JSON response and save the value for the reference_id parameter. You will need this to receive transaction status results, described on the Obtain Transaction Status Results page.

Congratulations! You’ve sent your first voice message with an OTP using TeleSign’s Voice Verify API and generated your first code snippet!
You can see more about available parameters for requests on the Voice with OTP Request (POST v1/verify/call) page.

Generate and Verify OTP Codes

There are two options to generate the verification code; either you or TeleSign can generate it. The choices are discussed in the following sections:

You Generate the Verification Code

Send a POST request with the verify_code parameter set to a code you generate:

phone_number=complete_phone_number_with_no_special_characters_or_spaces&language=en-US&verify_code=9876543&tts_message=Your code is $$CODE$$

Because you know the code that was sent to the end user, you can verify whether the value the user enters is correct.

TeleSign Generates the OTP Code

Send a POST request without specifying a verification code, and TeleSign generates the code value by default and sends it to the end user. For example:

phone_number=complete_phone_number_with_no_special_characters_or_spaces&language=en-US&tts_message=Your code is $$CODE$$

You then need to check whether the code that the user entered matches the one that TeleSign generated. After you receive the code that the user entered, send a GET request with verify_code as an input parameter set to the value the user entered. For example, if the code entered was 57244, your GET request would be as follows:
GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1

The combination of the reference ID for a transaction and the verification code entered by the end user is called completion data. While it is useful to always send this data in your requests to the Get Status API, it is not required unless you have TeleSign generate your verification codes for you.

You can learn more about completion data and the Get Status API on the Get Status API page.

You can also learn more by checking out the Obtain Transaction Status Results / Send Completion Data page for the Voice Verify API.

Enable Score with Voice Verify

If you choose to enable Score with Voice Verify, you will be able to assess a phone number's risk level for fraud (referred to as the phone number's score) prior to sending a voice verification message. Speak with our Customer Support Team to enable Score with Voice Verify. As part of the call, you will discuss what score is high enough to be blocked and we will configure blocking for you. You can also discuss for what specific countries you want Score to do blocking. If you want details about transactions, you will be able to see Score deails in responses after you enable Score.

You can find out more about Score on the following page:

An example response body when Score is enabled would look like this:

Voice Verify Response Body with Score Enabled

  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "call",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 133,
    "description": "Call blocked due to high risk score"
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  "voice": {
    "caller_id": "15551212 example only"
  "phone_type": {
    "code": "2",
    "description": "MOBILE"
  "risk": {
    "score": 900,
    "recommendation": "block",
    "level": "high"
  "numbering": {
    "phone_number": "5558675309 example only",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"

With Score enabled, the response you receive will have the same information as the regular Voice Verify response, plus the following additional parameters. They are:

numbering.country_codestringA 1, 2, or 3-digit number representing the country dialing code. For example, the country dialing code for both the U.S.A. and Canada is 1, and the country dialing code for the United Kingdom is 44.
numbering.max_lengthintegerThe maximum number of digits allowed for phone numbers with this particular country dialing code.
numbering. min_lengthintegerThe minimum number of digits allowed for phone numbers with this particular country dialing code.
numbering.phone_numberstringThe base phone number. This is simply the phone number without the country dialing code.
phone_type.codestringOne of the phone type codes
phone_type.descriptionstringText describing the phone type
risk.levelThe severity of the risk.
risk.recommendationstringThe action that TeleSign recommends that you take based on the risk score.
risk.scoreintegerThe risk score for this phone number.


You use a POST request to send your OTP voice message.

POST https://rest-ww.telesign.com/v1/verify/call HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:51p3DmaSH8oSfV0yHdAp9HNgifg=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com
Content-Length: 54

This is an example of a response TeleSign sends to your POST request.

Example POST Response

HTTP/1.1 200 OK
Date: Wed, 29 May 2015 00:09:08 UTC
Server: CERN/3.0 libwww/2.17
Content-Length: 314
Content-Type: application/json
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "submit_timestamp": "Wed, 06 Nov 2015 13:36:07 -0800",
  "sub_resource": "call",
  "errors": [],
  "status": {
    "updated_on": "2015-10-03T14:51:28.709526Z",
    "code": 100,
    "description": "Call answered"
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""

Did this page help you?