Skip to contentSkip to navigationSkip to topbar
On this page

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.

1
curl -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(link takes you to an external page) to learn more.

Release Stage and Access: Private Beta, please submit this form(link takes you to an external page) to contact sales. Requires carrier approvals.


Response properties

response-properties page anchor

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

PropertyDescription
MobileCountryCodeThe three digit mobile country code of the carrier, used with the mobile network code to identify a mobile network operator.
MobileNetworkCodeThe two-three digit mobile network code of the carrier, used with the mobile country code to identify a mobile network operator.
CarrierNameThe name of the carrier.
LastSimSwapAn 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.
ErrorCodeThe error code, if any, associated with your request.

LastSimSwap property values

lastsimswap-property-values page anchor
(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.

ValueDescription
LastSimSwapDateThe ISO-8601(link takes you to an external page) 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.
SwappedPeriodA threshold the customer has chosen during which SwappedInPeriod indicates if the SIM was changed for the specified mobile phone number within the threshold.
SwappedInPeriodA Boolean indicating whether the SIM was changed for the specified mobile phone number during the trailing SwappedPeriod.
SIM Swap LookupLink to code sample: SIM Swap Lookup
1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const 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
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9
10
async 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
18
fetchPhoneNumber();

Output

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
}

Need some help?

Terms of service

Copyright © 2024 Twilio Inc.