SIM Swap is in Private Beta. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support.
Use SIM Swap to retrieve details about the last SIM change for a mobile phone number. This helps you detect SIM swapping fraud and account takeovers. SIM Swap uses real-time authoritative data directly from mobile network operators. Learn more about Lookup SIM Swap.
SIM Swap is available for phone numbers in the following countries.
SIM Swap requires carrier registration and approval. Once approved, SIM Swap bills per request, even if no data is returned. Requests for unsupported countries or carriers returns null but won't result in a charge. For additional pricing information, contact Sales.
SIM Swap coverage depends on data from the major carriers in each country. However, during the Beta phase, it might not include all major carriers. For more information on coverage and pricing, contact Sales.
Note: SIM Swap requests for Canadian phone numbers won't return carrier information, including carrier_name, mobile_country_code, and mobile_network_code, unless you have special approval. Learn how to request access to Canadian Number Portability Administration Center (NPAC) data.
Make a GET /v2/PhoneNumbers/{PhoneNumber} request with the Fields=sim_swap query parameter.
1curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=sim_swap" \2-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
A SIM Swap request returns the following properties.
| 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- or 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 SIM was changed for a mobile phone number. |
ErrorCode | The error code, if any, associated with your request. |
During onboarding, you need to configure the SwappedPeriod for countries that don't support the LastSimSwapDate property. For countries where LastSimSwapDate is available, the SwappedPeriod calculates automatically and SwappedInPeriod sets to true.
The LastSimSwap object includes the following properties.
| 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. |
Learn more about the recommended implementation of LastSimSwap.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function fetchPhoneNumber() {11const phoneNumber = await client.lookups.v212.phoneNumbers("+447772000001")13.fetch({ fields: "sim_swap" });1415console.log(phoneNumber.simSwap);16}1718fetchPhoneNumber();
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": true14},15"carrier_name": "Vodafone UK",16"mobile_country_code": "276",17"mobile_network_code": "02",18"error_code": null19},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}