SIM Swap

Lookup's SIM Swap allows you to get information on the last SIM change for a mobile phone number. Learn more details about SIM Swap in the Lookup SIM Swap Overview.

SIM Swap Lookups are billed per Lookup, even if data is not available. Currently, requesting a SIM Swap Lookup for an unsupported country or carrier will return null values, but will not be billed.

To make a SIM Swap request, add sim_swap to the optional query parameter Fields when making a standard Lookup request.

1curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=sim_swap" \
2  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Coverage and Limitations: Countries in Europe, Latin America, and North America. See coverage. Canada carrier information, including carrier_name, mobile_country_code, and mobile_network_code, will not be returned in a SIM Swap request to a Canadian phone number unless you have special support. Please read this support article to learn more.

Release Stage and Access: Private Beta, please submit this form to contact sales. Requires carrier approvals.

Response properties

The following additional properties are returned for a SIM Swap request.

Property	Description
`MobileCountryCode`	The three digit mobile country code of the carrier, used with the mobile network code to identify a mobile network operator.
`MobileNetworkCode`	The two-three digit mobile network code of the carrier, used with the mobile country code to identify a mobile network operator.
`CarrierName`	The name of the carrier.
`LastSimSwap`	An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number. See LastSimSwap property values for more information.
`ErrorCode`	The error code, if any, associated with your request.

LastSimSwap property values

(information)

Info

During onboarding, you will be asked to configure the SwappedPeriod for all countries which do not support LastSimSwapDate. For countries that return the LastSimSwapDate, the SwappedPeriod will be automatically derived and SwappedInPeriod will be set to true.

The following properties are returned in the LastSimSwap object. See Using the last_sim_swap fields for more background.

Value	Description
`LastSimSwapDate`	The ISO-8601 date and timestamp for when the Subscriber Identity Module (SIM) was last changed for the specified mobile phone number. Only returned for GB, DE, ES, and NL.
`SwappedPeriod`	A threshold the customer has chosen during which `SwappedInPeriod` indicates if the SIM was changed for the specified mobile phone number within the threshold.
`SwappedInPeriod`	A Boolean indicating whether the SIM was changed for the specified mobile phone number during the trailing `SwappedPeriod`.

SIM Swap Lookup

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function fetchPhoneNumber() {
11  const phoneNumber = await client.lookups.v2
12    .phoneNumbers("+447772000001")
13    .fetch({ fields: "sim_swap" });
14
15  console.log(phoneNumber.simSwap);
16}
17
18fetchPhoneNumber();

Response

1{
2  "calling_country_code": "44",
3  "country_code": "GB",
4  "phone_number": "+447772000001",
5  "national_format": "07772 000001",
6  "valid": true,
7  "validation_errors": null,
8  "caller_name": null,
9  "sim_swap": {
10    "last_sim_swap": {
11      "last_sim_swap_date": "2020-04-27T10:18:50Z",
12      "swapped_period": "PT48H",
13      "swapped_in_period": true
14    },
15    "carrier_name": "Vodafone UK",
16    "mobile_country_code": "276",
17    "mobile_network_code": "02",
18    "error_code": null
19  },
20  "call_forwarding": null,
21  "line_status": null,
22  "line_type_intelligence": null,
23  "identity_match": null,
24  "reassigned_number": null,
25  "sms_pumping_risk": null,
26  "phone_number_quality_score": null,
27  "pre_fill": null,
28  "url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001"
29}