SMS Verify API - Screen recipients using Verify Plus (Legacy)

❗️

WARNING

This version is deprecated. To upgrade to the newest version of this product, reach out to our Customer Support Team. This product is available for full-service accounts only.

See this Changelog post for more information.

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

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

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 API account.
  2. Decide on a risk recommendation threshold in advance, in consultation with Telesign. For more explanation of how to interpret Intelligence results, see Understanding a risk recommendation for a phone number and the Intelligence 1.0 scale in the Intelligence documentation.

📘

NOTE:

Once this feature is enabled for your account, you do not need to include anything additional in your SMS Verify API 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 SMS Verify API.
  2. The phone number of the recipient included in the phone_number parameter is passed on to Intelligence for evaluation.

SMS Verify API 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=1234567890
&language=en-US
&template=Your code is $$CODE$$
  1. Verify Plus calculates a risk recommendation for that number. If the recommendation exceeds your threshold, the message is not sent. If the recommendation is equal to or below your threshold, the message is sent.
  2. Either way, SMS Verify API response body includes additional packages (phone_type, risk, numbering) with information related to the number and its fraud risk, including the risk recommendation.
  3. If the verification message is not sent due to a high risk recommendation, the property status.code in the response has a value of 233, and you are not charged for the SMS transaction. (You are charged for Intelligence).

SMS Verify API 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": "1234567890",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"
  }
}

SMS Verify API 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"
  }
}

Intelligence package schemas

numbering

PropertyTypeDescriptionExample
originalobjectAn object containing details about the original phone number included in the request.
original.phone_numberstringThe base phone number. This is the phone number without the country dialing code.7833012348
original.complete_phone_numberstringThe base phone number prefixed with the country dialing code.17833012348
original.country_codestringA 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.
cleansingobjectAn object containing details about how the phone number was cleansed. Phone cleansing corrects common formatting issues in submitted phone numbers.
cleansing.callobjectAn object containing cleansing details about a phone number used for receiving voice calls.
cleansing.call.cleansed_codeintegerOne 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_codestringA 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_lengthintegerThe maximum number of digits allowed for phone numbers with this particular country dialing code.10
cleansing.call.min_lengthintegerThe minimum number of digits allowed for phone numbers with this particular country dialing code.10
cleansing.call.phone_numberstringThe base phone number. This is simply the phone number without the country dialing code.7833012348
cleansing.smsobjectAn object containing cleansing details about a phone number used for receiving text messages.
cleansing.sms.cleansed_codeintegerOne 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_codestringA 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_lengthintegerThe maximum number of digits allowed for phone numbers with this particular country dialing code.10
cleansing.sms.min_lengthintegerThe minimum number of digits allowed for phone numbers with this particular country dialing code.10
cleansing.sms.phone_numberstringThe base phone number. This is simply the phone number without the country dialing code.7833012348

phone_type

PropertyTypeDescriptionExample
codestringOne of the phone type codes.2
descriptionstringText describing the phone type.MOBILE

risk

PropertyTypeDescriptionExampleValidations
levelstringThe severity of the risk.lowAllowed Values: low, medium, medium-high, high
recommendationstringThe action that Telesign recommends that you take based on the risk associated with the phone number.allowAllowed Values: allow, flag,block
scoreintegerThe risk recommendation for this phone number.