Screen SMS Verify Recipients by SIM Swap Indicator

This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify recipients using a SIM swap indicator before sending them a verification SMS. This feature is powered by a separate product, the TeleSign PhoneID SIM Swap Add-on.

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

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

Before You Begin

  • If your account is configured to include SIM Swap details in delivery notifications, make sure you have a Transaction Callback Service set up for your SMS Verify integration.

Step 1: Connect SIM Swap and SMS Verify

  1. Ask our Customer Support Team to enable SIM Swap for your SMS Verify account.
  2. Decide in consultation with TeleSign how you want the following options configured for SIM Swap:
    • Maximum SIM Swap Indicator: This is a value from 1-4, indicating the sensitivity of the SIM swap check. A value of 1 indicates the least risk of a SIM swap event, while 4 indicates the most risk. A verification SMS is only blocked if the risk value returned by the SIM Swap check exceeds the number you set. For more details on each risk value, see SIM Swap Add-on. The default value is 3.
    • Parameter: Perform the check on every transaction or only when a SIM swap parameter is passed in the request?
    • Countries: Perform the check on transactions to phone numebrs from every country or only to phone numbers from a list of countries?
    • Error Handling: Block sending of the verification SMS only when the maximum SIM swap indicator is exceeded or also when the SIM Swap check fails to complete? The check might fail to complete, for example, if information is not available about the phone number or it is from a country not included in our SIM Swap coverage.
    • SIM Swap Details in Delivery Status Callback: Do you want details of how the SIM Swap service processed your check request included in the delivery status notification callback for the SMS Verify transaction?
NOTE:

If you need to change your maximum SIM swap indicator value, contact our Customer Support Team.

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 REST API.
  2. The phone number of the recipient included in the phone_number parameter is passed on to SIM Swap for evaluation.
  3. If your account is configured to only use SIM Swap when a flag is included, include the parameter sim_swap_check with a value of true (highlighted below).
SMS Verify Request
HTTPS
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
&template=Your code is $$CODE$$
&sim_swap_check=true
  1. SIM Swap calculates a SIM swap indicator value for that number. If the value exceeds the maximum set for your account, the verification message is not sent. If the value is equal to or below the maximum, the message is sent.
  2. The SMS Verify API returns a response. Save the reference ID in the response (highlighted below); it can be used to get transaction status later.
SMS Verify Response
HTTPS
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": ""
  }
}
NOTE:

The API response only indicates whether the service successfully accepted the SIM Swap check request and the verification SMS request. To learn whether the message was successfully delivered, including whether sending was blocked due to the SIM Swap check, you will look for a request sent to your callback service for this transaction.

Step 3: Get Transaction Status

  1. Search for a request from TeleSign to your Transaction Callback Service for this integration, based on the reference_id from the SMS Verify transaction you saved earlier.
  2. The status.code and status.description properties in the payload of the callback indicate the delivery status all the way to the end-user.
  3. If the relevant setting is configured for your account, an additional sim_swap package is included in the callback payload (highlighted below), with details about the SIM Swap check results.
Example Callback Notification
HTTPS
POST /callback_endpoint HTTP/1.1
Host: your-callback-url.com
{ 
  "status": { 
     "updated_on": "2016-07-08T20:52:46.417428Z", 
     "code": 200, 
     "description": "Delivered to handset" 
   }, 
   "submit_timestamp": "2016-07-08T20:52:41.203000Z", 
   "errors": [], 
   "reference_id": "2557312299CC1304904080F4BE17BFB4",
   "verify": { 
     "code_state": "UNKNOWN", 
     "code_entered": null 
   }, 
   "sim_swap": {
    "swap_date": "2018-09-05",
    "swap_time": "22:00:00",
    "risk_indicator": 1,
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
   },  
   "sub_resource": "sms", 
   "additional_info": {
    "message_parts_count": 1,
    "price": "0.5112",
    "mnc": "03",
    "mcc": "220",
    "currency": "USD"
  }
}

Schema

This is the schema for the SIM swap package in the callback.

sim_swap
JSON
swap_date
string

The date of the SIM swap, if one is detected.

example: 2018-09-05
swap_time
string

The time of the SIM swap, if one is detected.

example: 22:00:00
risk_indicator
string

Indicates the likelihood that a SIM swap occured for this number. The response ranges between 1 and 4.

  • 1 - (very low) Swap did not occur or it occurred 15+ days ago.
  • 2 - (low) Swap occurred between 3 and 14 days ago.
  • 3 - (medium) Swap occurred in the last 72 hours.
  • 4 - (high) Swap occurred in the last 24 hours.
example: 1
status
object

Contains properties related to the status of the SIM Swap check.

code
integer

A code indicating the status of your request.

1 validation
description
string

Description of the status of your request.

1 validation