Phone ID - Identity attributes: SIM Swap

📘

NOTE:

To add this feature to your account, contact a Telesign expert. This feature is available for full-service accounts only.

The SIM Swap identity attribute allows you to find out whether or not the SIM for a submitted phone number has been swapped and if so, when. 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 property 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 responses

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": {}
    }
}

Response body - success

{
  "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:

Response body - timeout

{
    "sim_swap": {
        "status": {
            "code": 2811,
            "description": "Request processing timeout.",
        }
    }
}

Response body - no information found

{
  "sim_swap": {
    "status": {
      "code": 2805,
      "description": "No sim_swap identity attribute information for phone number."
    }
  }
}

Here is an example error response for when a phone number is out of coverage.

Response body - out of coverage

{
  "sim_swap": {
    "status": {
      "code": 2803,
      "description": "Phone number out of sim_swap identity attribute coverage."
    }
  }
}

An out of coverage error can occur when the phone number belongs to a carrier or a country for which SIM swap data is not available.

SIM Swap request parameters

ParameterTypeDescription
addonsobjectYou must have your Technical Account Manager enable this feature for use. This parameter allows you to receive information returned from your enabled identity attributes.
addons.sim_swapstringInclude this parameter to initiate use of the SIM Swap identity attribute.

SIM Swap response

PropertyTypeDescription
reference_idstringA 32-digit hex value used to identify a web service request. The value is unique to each web service request and is randomly generated by Telesign.
phone_typestringOne of the phone type codes.
descriptionstringText describing the phone type.
sim_swapobject
sim_swap.swap_datestringThe date of the swap, if applicable.
sim_swap.swap_timestringThe time the swap occurred, if applicable.
sim_swap.risk_indicatorintegerTelesign's assessment of how likely it is that a swap was carried out for a fraudulent purpose. Possible values are 1-4. 1 - (very low) swap did not occur or it occurred 15 days or more ago. 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 numeric code indicating the processing status of your request.
sim_swap.status.descriptionstringText description of the status code.