SMS Verify - Screen recipients using Verify Plus

This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify recipients using a Verify Plus risk score before sending them a verification SMS. This feature is powered by a separate product, the Telesign Score API.

You can do this all directly through the Verify API, without using the Score API. This is more efficient than making an additional call to the Score API.

Keep the reference page POST /v1/verify/sms open in another window while you work through these steps.

Step 1: Enable Verify Plus

  1. Ask our Customer Support Team to enable Verify Plus for your SMS Verify account.
  2. Decide on a risk score threshold in advance, in consultation with Telesign. For more explanation of how to interpret Score results, see Understanding your score and related details and the Score 1.0 scale in the Score API documentation.

📘

NOTE:

Once this feature is enabled for your account, you do not need to include anything additional in your SMS Verify request to ensure that it is evaluated by Verify Plus.

Step 2: Send the SMS

Once our Customer Support Team notifies you that this feature is enabled, follow these steps.

  1. Send a POST /verify/sms request to the Verify API.
  2. The phone number of the recipient included in the phone_number parameter is passed on to Score for evaluation.

SMS Verify request

POST /v1/verify/sms HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: rest-ww.telesign.com
phone_number=5552345678
&language=en-US
&template=Your code is $$CODE$$
  1. Verify Plus calculates a risk score for that number. If the score exceeds your threshold, the message is not sent. If the score is equal to or below your threshold, the message is sent.
  2. Either way, SMS Verify response body includes additional packages (phone_type, risk, numbering) with information related to the number and its fraud risk, including the risk score.
  3. If the verification message is not sent due to a high risk score, the property status.code in the response has a value of 233, and you are not charged for the transaction.

SMS Verify response: Not blocked

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 290,
    "description": "Message in progress"
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  },
  "phone_type": {
    "code": "2",
    "description": "MOBILE"
  },
  "risk": {
    "recommendation": "allow",
    "score": 82,
    "level": "low"
  },
  "numbering": {
    "phone_number": "5552345678",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"
  }
}

SMS Verify response: Blocked

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "sms",
  "errors": [],
  "status": {
    "updated_on": "2015-04-17T22:26:43.784963Z",
    "code": 233,
    "description": "Message blocked due to high risk score."
  },
  "verify": {
    "code_state": "UNKNOWN",
    "code_entered": ""
  },
  "phone_type": {
    "code": "2",
    "description": "MOBILE"
  },
  "risk": {
    "recommendation": "block",
    "score": 820,
    "level": "high"
  },
  "numbering": {
    "phone_number": "5552345678",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"
  }
}

Score package schemas

numbering

Property

Type

Description

Example

original

object

An object containing details about the original phone number included in the request.

original.phone_number

string

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

7833012348

original.complete_phone_number

string

The base phone number prefixed with the country dialing code.

17833012348

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

cleansing

object

An object containing details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.

cleansing.call

object

An object containing cleansing details about a phone number used for receiving voice calls.

cleansing.call.cleansed_code

integer

One of the phone number cleansing codes describing the cleansing operation Telesign performed on the phone number. The default value is 100 (no changes were made to the phone number).

100

cleansing.call.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 United Kingdom is 44.

1

cleansing.call.max_length

integer

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

10

cleansing.call.min_length

integer

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

10

cleansing.call.phone_number

string

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

7833012348

cleansing.sms

object

An object containing cleansing details about a phone number used for receiving text messages.

cleansing.sms.cleansed_code

integer

One of the phone number cleansing codes describing the cleansing operation Telesign performed on the phone number. The default value is 100 (no changes were made to the phone number).

100

cleansing.sms.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 United Kingdom is 44.

1

cleansing.sms.max_length

integer

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

10

cleansing.sms.min_length

integer

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

10

cleansing.sms.phone_number

string

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

7833012348

phone_type

Property

Type

Description

Example

code

string

One of the phone type codes.

2

description

string

Text describing the phone type.

MOBILE

risk

Property

Type

Description

Example

Validations

level

string

The severity of the risk.

low

Allowed Values: low, medium, medium-high, high

recommendation

string

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

allow

Allowed Values: allow, flag,block

score

integer

The risk score for this phone number.


Did this page help you?