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

SIM Swap response