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

This page explains how to use the Voice Verify API to send a verification code to an end-user. There are two options to generate the verification code; either you or TeleSign can generate it.

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:

Property

Type

Description

numbering.country_code

string

A 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_length

integer

The maximum number of digits allowed for phone numbers with this particular country dialing code.

numbering. min_length

integer

The minimum number of digits allowed for phone numbers with this particular country dialing code.

numbering.phone_number

string

The base phone number. This is simply the phone number without the country dialing code.

phone_type.code

string

One of the phone type codes

phone_type.description

string

Text describing the phone type

risk.level

The severity of the risk.

risk.recommendation

string

The action that TeleSign recommends that you take based on the risk score.

risk.score

integer

The risk score for this phone number.

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

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"
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  }
}

Did this page help you?