Smart Verify API Overview

The Smart Verify web service simplifies the process of verifying user identity by integrating several TeleSign web services into a single API call. This eliminates the need for you to make multiple calls to the TeleSign Verify resource. The Smart Verify API has a configurable workflow that encompasses realtime fraud detection, reputation scoring and optimized routing of the verification process (SMS or voice) to increase completion rates and lower cost while minimizing the integration effort to get started.

The Smart Verify web service is discussed in the following sections:

Workflow
Verify Methods
Supported
Request and Response Parameters
Obtain Verification Results / Send Completion Data
Smart Verify API Examples

Workflow

A call to the Smart Verify web service verifies an end user’s telephone number. If the number is blocklisted (a blocklisted number is a number that has been blocked because it is associated with fraudulent activity or is otherwise problematic), the attempt fails and TeleSign returns a corresponding status code. In addition, if the PhoneID score for the number is greater than the high risk score as configured in your account, then the request fails and TeleSign returns the appropriate status.

For numbers that are not blocked, TeleSign determines the best authentication method. If the phone is capable of receiving an SMS (a mobile phone for example), TeleSign chooses SMS Verify. If SMS Verify is not possible, TeleSign makes a Voice Verify call.

You can choose a preferred method in the call to the Smart Verify web service. Because it is not always possible to honor the selected preference (for example, an SMS message cannot be sent to a landline), TeleSign chooses the next best method.

NOTE:

TeleSign recommends that calls to the Smart Verify web service be made without a verification code, as this makes intercepting codes more difficult. If you do not specify a verification_code when calling the API, TeleSign generates one for you. You can verify that the code as returned by your end user is correct in one API call.

For information about scoring, refer to the Score page.

Verify Methods

After the Smart Verify web service determines the phone type, it uses that information to choose one of the following two TeleSign Verify methods:

SMS Verify
Voice Verify

NOTE:

Contact TeleSign Client Services for questions regarding how the Smart Verify API configures risk scores and determines blocked transactions.

Supported

The Smart Verify API supports the following:

Authentication - Basic (easiest to implement) and Digest
HTTP Methods -
- POST - When you send a POST request with the end user’s phone number to the API’s subresource (https://rest-ww.telesign.com/v1/verify/smart), the Smart Verify web service sends the verification code using the method determined best (as above) for the phone number in the request. This is typically the phone number that the end user submitted, although this can vary as TeleSign sometimes needs to modify the number in order to route it correctly.
- GET - After the verification request is made, you can retrieve the verification results or send completion data using a Get Status request or the Verify Transaction Callback web service. For a detailed discussion about how to obtain verification results, refer to the Get Status / Verify Transaction API page.
Content-Type - application/x-www-form-urlencoded

Request and Response Parameters

For a complete list of request and response parameters, refer to:

Obtain Verification Results / Send Completion Data

If you implemented your configuration so that TeleSign generates your one time passwords (OTPs), then you must send TeleSign completion data using a Get Status request. If you generate your own OTPs, 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:

Get Status request
- Refer to section Use Get Status to Request the Status of a Verify Transaction on the Get Status / Verify Transaction API page.
- For sending completion data, refer to section Use Get Status to Send Completion Data on the Get Status / Verify Transaction API page.
Verify Transaction Callback service (ideal for high volumes of transactions)
- You must contact your Technical Account Manager to set up this service.
- You must follow the instructions in the section Service Setup on the Get Status / Verify Transaction API page.

Smart Verify API Examples

The following examples demonstrate typical HTTP 1.1 Request/Response transactions for invoking the Smart Verify REST API, and for retrieving the verification results.

Invoke the REST API

Request

Invoke the Smart Verify REST API by sending a POST request message like this one to TeleSign’s web server.

POST Request Message

POST https://rest-ww.telesign.com/v1/verify/smart HTTP/1.1
Accept-Encoding: gzip,deflate
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
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: 59

phone_number=15555551234
   &ucid=TRVF
   &language=en-US

NOTE:

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

Response

TeleSign returns the following message in response to the preceding SMS Verify service request.

Response to POST Request

HTTP/1.1 200 OK
Date: Wed, 03 Oct 2012 14:51:28 GMT
Server: CERN/3.0 libwww/2.17
Content-Length: 316
Allow: GET,POST,HEAD
Content-Type: application/json

{
   "status": {
      "code": 290,
      "description": "Message in progress",
      "updated_on": "2016-02-11T23:32:35.364357Z"
   },
   "phone_type": {
      "code": "2",
      "description": "MOBILE"
   },
   "errors": [],
   "verify": {
      "code_state": "UNKNOWN",
      "code_entered": ""
   },
   "numbering": {
      "original": {
      "complete_phone_number": "13105551212",
      "country_code": "1",
      "phone_number": "3105551212"
      },
   "cleansing": {
      "sms": {
         "cleansed_code": 100,
         "country_code": "1",
         "max_length": 10,
         "min_length": 10,
         "phone_number": "3105551212"
      },
      "call": {
         "cleansed_code": 100,
         "country_code": "1",
         "max_length": 10,
         "min_length": 10,
         "phone_number": "3105551212"
      }
   },
   "sub_resource": "sms",
   "carrier": {
      "name": "SPRINT Spectrum L.P."
   },
   "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

Retrieve Verification Results

TeleSign retrieves the specific response from the underlying service in the synchronous response.

Information about verification results for the Verify subresources can be found at the following TeleSign website links:

All the services make use of the Get Status request or Verify Transaction Callback web service to obtain transaction results. If you have TeleSign generating your OTPs, you must additionally use the Get Status request to send completion data. For more information, refer to the Get Status / Verify Transaction API page.

Request

Use the reference_id of the Smart Verify service request as the subresource identifier.

Example Verification Request

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

Response

TeleSign returns the following message in response to the SMS Verify service request. (You used Smart Verify to send your request, but the SMS Verify subresource was used, thus a respones that has SMS Verify information in it.)

Example Response

HTTP/1.1 200 OK
Date: Wed, 29 May 2013 00:09:08 UTC
Server: CERN/3.0 libwww/2.17
Content-Length: 314
Allow: GET,POST,HEAD
Content-Type: application/json

{
   "status": {
      "code": 290,
      "description": "Message in progress",
      "updated_on": "2016-02-11T23:32:35.364357Z"
   },
   "phone_type": {
      "code": "2",
      "description": "MOBILE"
   },
   "errors": [],
   "verify": {
      "code_state": "UNKNOWN",
      "code_entered": ""
   },
   "numbering": {
      "original": {
      "complete_phone_number": "13105551212",
      "country_code": "1",
      "phone_number": "3105551212"
      },
   "cleansing": {
      "sms": {
         "cleansed_code": 100,
         "country_code": "1",
         "max_length": 10,
         "min_length": 10,
         "phone_number": "3105551212"
      },
      "call": {
         "cleansed_code": 100,
         "country_code": "1",
         "max_length": 10,
         "min_length": 10,
         "phone_number": "3105551212"
      },
   },
   "sub_resource": "sms",
   "carrier": {
      "name": "SPRINT Spectrum L.P."
   },
   "reference_id": "0123456789ABCDEF0123456789ABCDEF"
}

JSON Error Response

The following example illustrates the JSON response delivered by the following Smart Verify error code:

2028: “Blocked - risk score too high”

Example JSON Response Delivered by 2028 Error Code

{
  "reference_id": "B53931A87B64014C8802E7FA26D80098",
  "sub_resource": "smart",
  "errors": [],
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  },
  "status": {
    "updated_on": "2015-07-02T01:38:21.112435Z",
    "code": 2028,
    "description": "Blocked - risk score too high"
  }
}