Get Started with the Voice Verify API

The Voice Verify API delivers patented phone-based verification and two-factor authentication (2FA) using a one-time passcode (OTP) sent over voice message.

General Information

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

Send a Voice Message with a Verification Code

For details about sending your first voice message containing a one-time password (OTP), refer to the Send a Voice Message with a Verification Code page.

If you want to see the API reference, go to the Voice with OTP Request (POST v1/verify/call) page.

Obtain Verification Results / Send Completion Data

For details about obtaining details about transaction status, as well as providing completion data, refer to the Obtain Transaction Status Results page.

Response When You Enable Score

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, without having to implement the Score API.

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"
  },
  "phone_type": {
    "code": "2",
    "description": "MOBILE"
  },
  "risk": {
    "score": 900,
    "recommendation": "block",
    "level": "high"
  },
  "numbering": {
    "phone_number": "5558675309",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"
  }
}

You can learn more about this option in the Enable Score with Voice Verify section on the Send a Voice Message with a Verification Code page.

Voice Verify Examples

This section contains examples of requests and responses for the Voice Verify API.

POST Request and Response Examples

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

Example POST Request with Voice Verify
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=15555551234
   &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": ""
   }
}

This is an example response when you enable Score:

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"
  }
}

GET Request and Response Examples

You retrieve the verification results by sending a GET request message to the TeleSign web server. You use the reference_id of the Verify Call service request as the subresource identifier.

Example GET Request for a Voice Verify Transaction
GET https://rest-ww.telesign.com/v1/verify/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com

This is an example of a response sent to your GET request:

Example GET 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",
   "sub_resource" : "call",
   "errors": [],
   "status": {
      "updated_on": "2015-10-03T14:51:28.709526Z",
      "code": 130,
      "description": "Call blocked by TeleSign"
},
   "call_forwarding": {
      "action": "BLOCK",
      "call_forward": "FORWARDED"
   },
   "voice" : {
     	"caller_id" : "15555551212 - example only"
   },
      "verify": {
      "code_state": "UNKNOWN",
      "code_entered": ""
  }
}

Transaction Callback Service Example

The following example illustrates the JSON objects delivered by the TeleSign Verify Transaction Callback Web Service.

HTTP/1.1 200 OK
Date: Wed, 06 Nov 2015 13:35:40 -0800
Server: CERN/3.0 libwww/2.17
Content-Length: 296
Allow: GET
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": ""
   },
   "voice" : {
     	"caller_id" : "15555551212 - example only"
   },
}

Verifying a TeleSign-Generated Verification Code

When TeleSign generates the value of the verification code, you can check whether the code that the user entered matches the one that TeleSign generated. To do this, send a GET request with verify_code as an input parameter, and set it to the value the user entered. For example, if the code entered was 57244, you would make the GET request as follows:

GET https://rest-ww.telesign.com/v1/verify/AEBC93B5898342F790E4E19FED41A7DA?verify_code=57244 HTTP/1.1

If the code that you sent in the GET request matches the TeleSign-generated code, the value of code_state will be ‘valid’ in the response:

Example Response Body When You Send the Verification Code
{
   "reference_id" : "AEBC93B5898342F790E4E19FED41A7DA",
   "sub_resource" : "call",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 103,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "valid",
      "code_entered" : "57244"
   },
   "voice" : {
     	"caller_id" : "15551212 - example only"
   },
}

Buy a Phone Number (Caller ID)

TeleSign offers the option of buying a caller ID to use to send messages to your end users. A sender ID is sometimes referred to as a dedicated phone number.

You can use the Phone Numbers API to buy a phone number. This is best if you do not need to buy numbers in areas that have special restrictions. Details about the Phone Numbers API (and what areas have restrictions) are available on the Get Started with the Phone Numbers API page.

Alternatively, you can speak with your TAM to purchase one or more phone numbers to use as a caller ID. You need at least one if you want to receive messages using Inbound SMS.

Text-to-Speech Hints

When making a voice call, you can choose to have a text-to-speech (TTS) translation of a text message to speech, instead of using TeleSign’s default message. To use the TTS feature, call the Voice Verify method, specifying the language from the list of supported languages and countries.

All TeleSign TTS voices are female. Most generic text will be spoken as expected, with pauses for commas, semicolons, dashes, and at the end of a sentence. You can create a longer pause between words by using a newline character ( “\n” ). Depending on what language you are coding in, you will need to create the newline character as appropriate. For example, if you are using Python, “\n” is correct. For a shorter pause, use a colon ( “:” ) or semicolon ( “;” ).

NOTE:

The TTS parameter allows UTF-8 strings, therefore it can accept Unicode characters.

TTS is generally quite robust for spoken text, because the words are typically for general use. However, there are some caveats, especially when using TTS for non words (such as URLs) or for auto-generated words (such as company names).

The only reliable way to know that you’re producing speech that sounds the way you want to is to generate a test call with the string in the language you want to use. Listening, ideally by a native speaker, is the best way to troubleshoot this feature.

General Hints

  • Strings sent to the TTS engine outside of typical words found in the dictionary, such as URLs, email addresses and company names, may be fully pronounced, spelled out, or a combination of the two.
  • The system does what it can to pronounce all words included in the message text. This mostly depends on how close an actual word in the string is similar to a word found in the dictionary. Therefore, even made up words can be interpreted if they resemble a word in the dictionary. Although the pronunciation gets less predictable as the pronunciation gets further from the expected word.
  • TeleSign attempts to pronounce words that are unpronounceable. Although this can lead to rather odd results when a phrase in one language is pronounced by a voice in another language or dialect. In some cases, the result is not as expected (for example, “gmail.com” may be pronounced as “graymail.com”).
  • Semi-colons are the most reliable way to include a space between pronounced words/numbers. A long pause can also be included by adding a newline in the message. Therefore, “1;2;3\n4;5;6” (the backslash is essential) will pronounce the first group of three digits, pause and then pronounce the second.
  • Numbers, URLs and made up words are covered for English, but the same lessons are likely to apply to other languages.

Numbers

Most of the following tips for numbers apply to English languages only, using standard text with common words found in the dictionary. Less common words are not as likely to be pronounced properly, and non-dictionary words are unpredictable and vary with the dialect and language.

  • Semi-colons are the most reliable way to put space between pronounced words/numbers. For example, “1;2;3;4;5” reads the digits in sequence and is slower than “1 2 3 4 5” . “12345” sounds to me very much like the one with spaces) but “12,345” is “twelve thousand three hundred forty five”, “123,45” is “one hundred twenty three (pause) forty five”, “1234,5” is “twelve thirty four (pause) five”.
  • Commas work in some languages as effective pauses, but in other languages (French for example) the comma is read (in French “virgule”). So in English “1,2,3,4,5” reads the digits separately with space between them. In French, the digits are read with “virgule” spoken between them.
  • Digits used in strings are read (in “en-US” at least) in pairs, but it depends on the context. For example, a phone number like “1-559-555-5643” in “en-US” is read digit by digit (with pauses at the dashes) but “1;559;555;5653” is read as “one five fifty nine five fifty five fifty six forty three”. This varies from place to place, so in some combinations the “-” is silent, in others “dash” and in others, “hyphen”. In some places, the “559” is “five hundred fify nine”. In “en-IN” the “5643” is “five hundred sixty four three”, in another it is “five thousand six hundred and forty three” and in another it is “fifty six forty three”.
  • Most other punctuation provides as a slight pause, but not a long pause. Most punctuation is generally not pronounced.

Next Steps

This section offers some suggestions for next steps to take.