SMS Verify API - Screen recipients by SIM swap indicator

This page walks you step-by-step through how to screen out potentially fraud-related SMS Verify API 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 SMS 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:

• Upgrade your account: Upgrade to a paid account if you are using a trial account.
• "From" phone number: You must buy a “from” phone number from Telesign before sending OTPs to any number other than the one you registered your account with.
• Transaction Callback Service: Set up Transaction Callback Service which is required to receive notifications from Telesign about the status of your transactions.

Step 1: Connect SIM Swap and SMS Verify API

1. Ask the Telesign Customer Support Team to enable SIM Swap for your SMS Verify API 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 API 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 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.

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=5552345678
&template=Your code is $$CODE$$
&sim_swap_check=true

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

SMS Verify API 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 API 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.