Phone ID - Identity attributes: SIM Swap

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

Parameter

Type

Description

addons

object

You 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_swap

string

Include this parameter to initiate use of the SIM Swap identity attribute.

SIM Swap response

Property

Type

Description

reference_id

string

A 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_type

string

One of the phone type codes.

description

string

Text describing the phone type.

sim_swap

object

sim_swap.swap_date

string

The date of the swap, if applicable.

sim_swap.swap_time

string

The time the swap occurred, if applicable.

sim_swap.risk_indicator

integer

Telesign'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.status

object

sim_swap.status.code

string

A numeric code indicating the processing status of your request.

sim_swap.status.description

string

Text description of the status code.


Did this page help you?