SMS Verify API - Screen Recipients by Risk Score
This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify recipients using a risk score before sending them a verification SMS. This feature is powered by a separate product, TeleSign Score.
You can do this all directly through the SMS 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: Connect Score and SMS Verify
- Ask our Customer Support Team to enable Score for your SMS Verify account.
- 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 in the Score 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 Score.
Step 2: Send the SMS
Once our Customer Support Team notifies you that this feature is enabled, follow these steps.
- Send a
POST /verify/sms
request to the SMS Verify REST API. - 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$$
- Score calculates a risk score for that number. If the score exceeds your threshold, the verification is not sent. If the score is equal to or below your threshold, the message is sent.
- Either way, the SMS Verify API response body includes additional packages (phone_type, risk, risk_insights, numbering) with information related to the number and its fraud risk, including the risk score.
- If the verification message is not sent due to a high risk score, the property
status.code
in the response has a value of233
, 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": "very low"
},
"risk_insights": {
"status": 800,
"category": [
10002
],
"a2p": [
20001,
20101,
21002
],
"p2p": [
30004,
30101,
30201,
30302,
31008
],
"number_type": [
40005,
40011
],
"ip": [
50001,
50004
],
"email": [
60003,
60006
]
},
"numbering": {
"phone_number": "5558675309",
"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": "very high"
},
"risk_insights": {
"status": 800,
"category": [
10002
],
"a2p": [
20001,
20101,
21002
],
"p2p": [
30004,
30101,
30201,
30302,
31008
],
"number_type": [
40005,
40011
],
"ip": [
50001,
50004
],
"email": [
60003,
60006
]
},
"numbering": {
"phone_number": "5558675309",
"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 | |
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 |
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 |
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 |
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: |
recommendation | string | The action that TeleSign recommends that you take based on the risk score. | allow | Allowed Values: |
score | integer | The risk score for this phone number. |
risk_insights
Property | Type | Description | Example |
---|---|---|---|
status | integer | The processing status of the risk insights package for this request. | 800 |
category | array (of integers) | Reason codes related to the category of the phone number. Insights Reason Code Mappings provides the meaning of the codes returned. | [10002] |
a2p | array (of integers) | Reason codes specific to application-to-person communication (A2P). These are automated communications sent to a human, like verification codes, appointment reminders, etc. Insights Reason Code Mappings provides the meaning of the codes returned. | [20001,20101,21002] |
p2p | array (of integers) | Reason codes specific to person-to-person communication (P2P). This is two-way communication between two humans, like one friend texting another. Insights Reason Code Mappings provides the meaning of the codes returned. | [30004,30101,30201,30302,31008] |
number_type | array (of integers) | Reason codes related to the phone number’s type. Insights Reason Code Mappings provides the meaning of the codes returned. | [40005,40011] |
ip | array (of integers) | Reason codes related to activity of the IP you provided for this phone number. Insights Reason Code Mappings provides the meaning of the codes returned. | [50001,50004] |
array (of integers) | Reason codes related to activity of the email address you provided for this phone number. Insights Reason Code Mappings provides the meaning of the codes returned. | [60003,60006] |
Updated 4 months ago