Want to provide feedback?

Write to docs@telesign.com.

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

Voice Verify API Explorer
NOTE: When using the Voice Verify API Explorer, you will be charged your contracted rate for each transaction. The time shown in ms is not indicative of regular transmission rates, and only applies to the Voice Verify API Explorer.
Send requests directly from the browser (CORS must be enabled)
$$.env
No $$.env variables are being used in this request.

Use these instructions with the Voice Verify API Explorer (above) 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.

The rest of this page provides additional details about TeleSign’s Voice Verify API. You can choose from these options:

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.

Y 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 when Score is enabled would look like this:

Voice Verify Response 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:

ValueDescription
numbering
ValueDescription
country_codeA 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.
max_lengthThe maximum number of digits allowed for phone numbers with this particular country dialing code.
min_lengthThe minimum number of digits allowed for phone numbers with this particular country dialing code.
phone_numberThe base phone number. This is simply the phone number without the country dialing code.
phone_typeAn object containing details about the phone type. This object contains the following parameters:
ValueDescription
codeOne of the phone type codes
descriptionText describing the phone type
riskAn object that describes the risk score for the phone number specified in the request; it contains the following parameters:
ValueDescription
levelA string indicating the severity of the risk
recommendationA string indicating the severity of the risk
scoreOne of the scores and risk levels values

Examples

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

phone_number=complete_phone_number_with_no_special_characters_or_spaces
   &ucid=TRVF
   &originating_ip=203.0.113.45
   &language=en
   &call_forward_action=block
NOTE:

The request parameters are shown on separate lines for illustration purposes.

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
Allow: GET,POST,HEAD
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"
   },
   "call_forwarding": {
      "action": "FLAG",
      "call_forward": "FORWARDED"
   },
   "verify": {
      "code_state": "UNKNOWN",
      "code_entered": ""
   }
}

Next Steps

This section offers some suggestions for next steps to take.