Voice Verify API - Screen recipients using Verify Plus

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

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

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

Keep the reference page POST /v1/verify/call 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 Voice 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 Voice Verify API request to ensure that it is evaluated by Verify Plus.

Step 2: Send the voice message

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

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

Voice Verify API request

POST /v1/verify/call 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$$

3. Verify Plus calculates a risk recommendation for that number. If the recommendation exceeds your threshold, the call is initiated. If the recommendation is equal to or below your threshold, the call is not initiated.
4. Either way, the Voice 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.
5. 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 transaction.

Voice Verify API response: Not blocked

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

Voice Verify API response: Blocked

HTTP/1.1 200 OK
Content-Type: application/json
{
  "reference_id": "ABCDEF0123456789ABCDEF0123456789",
  "sub_resource": "call",
  "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": "very high"
  },
  "numbering": {
    "phone_number": "5552345678",
    "min_length": 10,
    "max_length": 10,
    "country_code": "1"
  }
}

Intelligence package schemas

numbering

phone_type

risk