SMS Verify - Screen 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 Telesign product, the SIM Swap identity signal.

You can do this all directly through the Verify API. This is more efficient than making an additional call to SIM Swap.

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

Before you begin

Make sure you have the following set up:

Step 1: Connect SIM Swap and SMS Verify

  1. Ask the Telesign 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 Phone ID - Identity signals: SIM Swap. 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 numbers 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 the Telesign 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 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.

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
&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 Verify API returns a response. Save the reference ID in the response; it can be used to get transaction status later.

SMS Verify response

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

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.

Property

Type

Description

Example

swap_date

string

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

2018-09-05

swap_time

string

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

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.

1

status

object

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

status.code

integer

A code indicating the status of your request.

2800

status.description

string

Description of the status of your request.

Request successfully completed


Did this page help you?