SIM Swap Add-on

The SIM Swap add-on allows you to find out whether or not the SIM for the phone number has been swapped and if so, at what point. TeleSign evaluates how likely it is that the SIM swap was for a fraudulent reason using a scale from 1-4. The scale is provided as part of the risk_indicator parameter in the response. Possible values are:

  • 1 - (very low risk) A swap did not occur, or it occurred more than 15 days ago.
  • 2 - (low risk) A swap occurred some time between the last 3 and 14 days.
  • 3 - (medium risk) A swap occurred in the last 72 hours.
  • 4 - (high risk) A swap occurred the same day.

The information you get in a response includes:

  • Risk indicator
  • Swap date
  • Swap time (if available)

Example Request and Response for SIM Swap

This section provides examples of a request to use the SIM Swap add-on, and various responses.

A SIM Swap request looks like this:

SIM Swap Request
POST https://rest-ww.telesign.com/v1/phoneid/15555551212 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:vjE/ZDfPvDkuGNsuqCFFO4neYIs=
Date: Thu, 08 Nov 2018 14:11:09 GMT
Content-Type: application/json 

{
    "addons": {
        "sim_swap": {}
    }
}

Here is an example of a successful response body for SIM Swap:

Successful Response Body for SIM Swap
{
  "sim_swap": {
    "swap_date": "2018-09-05",
    "swap_time": "22:00:00",
    "risk_indicator": 1,
    "status": {
      "code": 2800,
      "description": "Request successfully completed"
    }
  }
}

This is an example error response body for when a SIM Swap request times out:

Error Response Body for a Timeout
{
    "sim_swap": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

This is an error response body when there is no information found:

Error Response Body for No Information Found
{
  "sim_swap": {
    "status": {
      "code": 2805,
      "description": "No sim_swap add-on information for phone number."
    }
  }
}

Here is an example error response for when a phone number is out of coverage. This kind of error can occur when the phone number belongs to a carrier or a country for which SIM swap data is not available.

Error Response Body for Phone Number Out of Coverage
{
  "sim_swap": {
    "status": {
      "code": 2803,
      "description": "Phone number out of sim_swap add-on coverage."
    }
  }
}
SIM Swap Request Parameters
object
addons
object

You must have you Technical Account Manager enable this feature for use. The addons parameter allows you to receive information returned from Contact, Contact Plus, Contact Match, or Number Deactivation, depending on which add-ons you enable. You receive add-on information back along with standard PhoneID information.

SIM Swap Response
object
reference_id
string

A 32-digit hex value used to identify the web service requests. The value is unique to each web service request, is randomly generated by TeleSign, and is returned in the response message immediately following the web service request.

phone_type
string

One of the phone type codes.

description
string

Text describing the phone type.

sim_swap
object