PhoneID API - Add-ons: SIM Swap

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

ParameterTypeDescription
addonsobjectYou 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.
addons.sim_swapstringThe SIM Swap add-on allows you to determine whether or not the SIM for the phone number has been swapped and how recently the swap occurred. TeleSign evaluates how likely it is that the SIM swap was for a fraudulent reason using a scale from 1-4.

SIM Swap Response

PropertyTypeDescription
reference_idstringA 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_typestringOne of the [phone type code](https://enterprise.telesign.com/docs/codes-languages-and-time-zones#section-phone-type-codes\).
descriptionstringText describing the phone type.
sim_swapobject
sim_swap.swap_datestringIf the number has been sim swapped, the date of the swap appears here.
sim_swap.swap_timestringIf the number has been sim swapped, this field indicates at what time the swap occurred.
sim_swap.risk_indicatorintegerThis field shows TeleSign's assessment for how likely it is to have been a swap that was carried out for a fraudlent purpose. The response is a number 1-4. 1 - (very low) swap did not occur or it occurred in the last 15+ days. 2 - (low) swap occurred some time between the last 3 and 14 days. 3 - (medium) swap occurred in the last 72 hours. 4 - (high) swap occurred same day.
sim_swap.statusobject
sim_swap.status.codestringA status code describing the status of your request.
sim_swap.status.descriptionstringDescription of the status code.

Did this page help you?