TeleSign Developer Center

Welcome! This resource hub provides documentation and references on API & SDK integration and other product-related information.

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

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

READ THIS NOTE:

This documentation is intended for you if you use the Enterprise versions of TeleSign products.

You use Enterprise TeleSign products if you log in to your account at teleportal.telesign.com, use endpoints that begin with rest-ww.telesign.com, and have a designated Technical Account Manager (TAM).

If you log in to your account at portal.telesign.com, are using TeleSign's free trial, have endpoints that begin with rest-api.telesign.com, and do NOT have a TAM, you need the Standard API Docs page.

Before getting started, make sure to review the following pages:

The TeleSign Voice Verify product includes the Verify Call web service, which sends a verification code to your end user in a voice message with a phone call.

The documentation for the Verify Call web service includes the following sections:

URI

To use the Verify Call web service, send a POST request to the following URI.
https://rest-ww.telesign.com/v1/verify/call

NOTE:

If you are using rest-telesign.com endpoints, TeleSign recommends that you upgrade to the new base URI (rest-ww.telesign.com as soon as possible). It is faster.

Information Returned
The Verify Call web service returns the following pieces of information:

  • Status
    • Code
    • Description
    • Updated On
  • Verify
    • Code State

Verifying the Code

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=15555551234
&ucid=TRVF
&originating_ip=203.0.113.45
&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 verification code

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

phone_number=15555551234
&ucid=TRVF
&originating_ip=203.0.113.45
&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

For more information, see Verifying a TeleSign-Generated Verification Code.

Obtain Verification Results / Send Completion Data

If you implemented your configuration so that TeleSign generates your codes, then you must send TeleSign completion data using a Get Status request. If you generate your own codes, sending completion data is optional, but recommended. (Completion data is the reference ID associated with an end user's transaction, and the verification code entered by the end user.)

Verification results are then made available to you using the verification method you select, either:

Supported HTTP Methods

POST
When you send a POST request with the user’s phone number to the /v1/verify/call/ subresource, TeleSign places a call to your user. When the call is answered by your user, an automated voice communicates a verification code. The user completes the verification procedure by entering this code on your website.

The URI for a POST request is /v1/verify/call/.

GET
After you’ve made your verification request, you can retrieve the verification results by sending a GET request to the /v1/verify/ resource, with a reference to your original service request for the Subresource Identifier. TeleSign returns a response message that contains the verification results in the form of a verify JSON object in the entity body.

The URI for a GET request is /v1/verify/[reference_id].

HEAD
Although supported, use of the HEAD method is limited to testing because the response message returned from the web server does not contain an entity-body.

Requests

Headers

This section provides a summary of required and optional headers for a request. For details about how to use them for proper authentication, review the section Authentication. For more details about these headers, review the section Standard and TeleSign Specific Headers.

General Headers

  • Content-Type - Required for POST requests. Ignored for GET requests, but you must mark its position with a newline for StringToSign.
  • Date - Required unless you include X-TS-Date. If you do not include the Date header value, you must mark its position with a newline character for StringToSign.

Request Headers

TeleSign-Specific HTTP Headers

  • X-TS-Date - Optional, you may use this instead of the Date header.
  • X-TS-Nonce - Optional, specifies a unique, random nonce string. You can include this header to provide additional protection against malicious replay attacks
  • X-TS-Auth-Method - Required for HMAC-SHA256. If you do not include this header, signature authentication defaults to HMAC-SHA1.

Request Parameters

POST
The following parameters are supported in the body of a POST request:

phone_number

  • [Required] Your end user’s phone number, including the country code.

  • [Example] phone_number=13105551212

ucid

  • [Optional] A string that specifies one of the use case codes.

  • [Example] ucid=TRVF

originating_ip

  • [Optional] 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.
  • [Example IPv4] originating_ip=203.0.113.45
  • [Example IPv6] originating_ip=2001:db8:85a3::8a2e:370:7334

call_forward_action

  • [Optional] Specifies the action that you want TeleSign to perform if the phone number has Call Forwarding enabled. Valid values include block and flag.
    • Block - If set to block, TeleSign services abort the verification process immediately, and return the call status code 130 - Call Blocked by TeleSign.
    • Flag - If set to flag, then TeleSign continues the verification process as usual. This also returns an indicator identifying the phone number as having Call Forwarding enabled, giving you the option of processing the phone number.
  • [Default] TeleSign processes the verification request by performing a Call Forwarding detection check.

  • [Example] phone_number=15555551234&ucid=TRVF&language=en&call_forward_action=block

language

  • [Optional] The IETF language tag used in applying predefined templates. For a complete list of language tags, see the section Supported Languages for Messages on the Codes, Languages, and Time Zones (REST) page.

  • [Example] language=fr-CA

  • [Default] en-US

verify_code

  • [Optional] The verification code used for the code challenge. This is a randomly-generated numeric value. By default, TeleSign automatically generates a five-digit value for you.

  • If you prefer to use your own verification code, you can override the default behavior by including this parameter and giving it a numeric value between 100 and 99999.

  • [Example] verify_code=71965
  • [Default] By default, you don’t include this parameter (and therefore, TeleSign provides the verification code).

tts_message

  • [Optional] Allows you to pass a text-to-speech (TTS) message.

  • [Example] tts_message= "Hello, your secret code is $$CODE$$. Thank you", language="en-US"

  • [Default] TeleSign sends a default message to the phone. Messages default to en-US, unless otherwise stated by the language parameter. The default message is "Hello. Thank you for using our phone verification system. Your code is [code]. Once again, your code is [code]. Goodbye."

NOTE:

To generate a TeleSign assigned validation code (this is recommended), include $$CODE$$ in the message string. This generates a random string with the appropriate length as part of the TTS message.

extension_type

  • [Optional] It’s 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.

  • [Examples] extension_type=1 (for Automated Attendants) extension_type=2 (for Live Operators)

  • [Default] By default, you do not include this parameter, and you can use Verify Call with direct-dialed phones numbers only.

NOTE:

When you use this parameter, you must also use extension_template.

extension_template

  • [Optional] 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.

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

  • [Example] The PBX Automated Attendant prompt says “Press ‘1’ to enter your party’s extension,” and the user’s extension is ‘333’.

  • extension_template=1,333

  • [Default] By default, you do not include this parameter.

NOTE:

When you use this parameter without specifying a value for extension_type, then extension_type=1 is used automatically.

redial

  • [Optional] A Boolean value that specifies whether the TeleSign system redials when the call fails. If this parameter is set to false, then the TeleSign system does not reattempt calling the phone number when the first call attempt fails.

  • [Default] true
  • [Example] redial=false

GET
The following parameters are supported in a GET request.

Use the reference_id as the subresource identifier in your GET request.

reference_id

  • [Required] The reference identifier that TeleSign generates and returns in its response to your verify/call service request. This value uniquely identifies each TeleSign web service request.

  • [Example] https://rest-ww.telesign.com/v1/verify/ABCDEF0123456789ABCDEF0123456789

NOTE:

If you supply the verification code when you POST your service request to Verify Call, and if the end user enters it back into your web application, then you do not need to contact TeleSign to get the verification result because you already have the two codes.

Responses

This section details the response message returned by the Verify Call web service.

Response Headers

The TeleSign server returns the following headers for this subresource:

Allow

  • Indicates the HTTP methods that the resource supports. The allowed methods for this web service are GET, POST, and HEAD.

Content-Type

  • Specifies the media type of the response message’s payload (that is, of the data contained in the response message’s entity-body). Telesign web services always return results in the application/json media type.

Response Body

The response body contains a JSON object with the following keys:

NOTE:

Unless otherwise specified, a missing or unspecified key value defaults to null.

reference_id

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

resource_uri

  • The URI to poll for the verification result. The URI is simply /v1/verify/[reference_id].

sub_resource

  • The subresource to access; it is set to call.

errors

  • 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.
    ValueDescription
    codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
    descriptionA string that describes the type of error that occurred.
    If no errors occur, then this array is empty. "errors": []

status

  • 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:
    • code
      • A three digit numeric code that corresponds to the current state of the web service call. See the section Call Status Codes below for the complete listing.
      description
      • The text version of the call status code.
      updated_on
      • An ISO 8601 UTC timestamp indicating when the status was updated.

verify

  • An object that indicates the verification result. This object contains the following key:
      code_state
      • A string value that indicates the verification result. VALID, INVALID, and UNKNOWN. When the verification is still in progress, code_state is UNKNOWN.

call_forwarding

  • Specifies the action that you want TeleSign to perform if the phone number has Call Forwarding enabled. This object contains the following keys:
      action
      • A string value that indicates the action taken if the phone number was found to have Call Forwarding enabled. Possible values are FLAG and BLOCK.
      call_forward
      • A string value that indicates whether the phone number has Call Forwarding enabled. Possible values are FORWARDED, NOT_FORWARDED, UNSUPPORTED, and UNAVAILABLE (if the Call Forwarding status could not be determined).

sub_resource

  • The subresource to access; it is set to call.

errors

  • 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.
    ValueDescription
    codeA 1 to 5-digit error code (possibly negative) that indicates the type of error that occurred.
    descriptionA string that describes the type of error that occurred.
    If no errors occur, then this array is empty. "errors": []

status

  • 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:
      code
      • A three digit numeric code that corresponds to the current state of the web service call. See the section Call Status Codes below for the complete listing.
      description
      • The text version of the call status code.
      updated_on
      • An ISO 8601 UTC timestamp indicating when the status was updated.

verify

  • An object that indicates the verification result. This object contains the following key:
      code_state
      • A string value that indicates the verification result. VALID, INVALID, and UNKNOWN. When the verification is still in progress, code_state is UNKNOWN.

Responses 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. Speak with your Technical Account Manager (TAM) to enable Score with Voice Verify. As part of the call, you will discuss what score is high enough to be blocked and the TAM 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 details 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:

{
   "reference_id" : "ABCDEF0123456789ABCDEF0123456789",
   "resource_uri" : "/v1/verify/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" : ""
   },
   "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"
   }   
}

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

  • ValueDescription
    country_code 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.
    max_length The maximum number of digits allowed for phone numbers with this particular country dialing code.
    min_length The minimum number of digits allowed for phone numbers with this particular country dialing code.
    phone_number The base phone number. This is simply the phone number without the country dialing code.

phone_type

  • An object containing details about the phone type. This object contains the following parameters:
    Value Description
    code One of the phone type codes
    description Text describing the phone type

risk

  • An object that describes the risk score for the phone number specified in the request; it contains the following parameters:
    Value Description
    level A string indicating the severity of the risk.
    recommendation A string indicating the action that TeleSign recommends that you take based on the risk score
    score One of the scores and risk levels values

Examples

The following examples demonstrate typical HTTP 1.1 Request/Response transactions for invoking the Verify Call web service, and for retrieving the verification results.

Invoking the Web Service

Request

You invoke the web service by sending a POST request message like this one, to the TeleSign web server.

POST https://rest-ww.telesign.com/v1/verify/call HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: d4fbb39a-5b8a-4d47-9670-73492215e5c7
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:51p3DmaSH8oSfV0yHdAp9HNgifg=
Date: Wed, 03 Oct 2015 14:51:26 -0700
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.

Response

TeleSign returns the following message in response to the preceding example request.

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

Retrieving Verification Results

You retrieve the verification results by sending a GET request message to the TeleSign web server.

Request

You use the reference_id of the Verify Call service request as the subresource identifier.

GET https://rest-ww.telesign.com/v1/verify/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Accept-Encoding: gzip,deflate
X-TS-Auth-Method: HMAC-SHA256
X-TS-Nonce: 4b33a3af-fd87-421d-b494-dafdc36b0b00
Authorization: TSA 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Date: Wed, 03 Oct 2015 14:53:11 -0700
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
Host: rest-ww.telesign.com

Response

TeleSign returns the following message in response to the preceding example request.

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

Callback Service Verification Results

The following example illustrates the JSON objects delivered by the TeleSign Verify Transaction Callback 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": ""
   }
}

Verifying a TeleSign-Generated Verification Code

Request

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

Response

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:

{
   "reference_id" : "AEBC93B5898342F790E4E19FED41A7DA",
   "resource_uri" : "/v1/verify/AEBC93B5898342F790E4E19FED41A7DA",
   "sub_resource" : "call",
   "errors": [],
   "status" : {
      "updated_on" : "2015-04-17T22:26:43.784963Z",
      "code" : 290,
      "description" : "Message in progress"
   },
   "verify" : {
      "code_state" : "valid",
      "code_entered" : "57244"
   }
}

Text-to-Speech (TTS) 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;3n4;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.

Call Status Codes

This table lists the status codes (and the associated strings) returned in response to a Voice Verify service request.

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 attempted

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.

Enterprise Voice Verify API