Skip to contentSkip to navigationSkip to topbar
Rate this page:
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.


_10
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=sim_swap" \
_10
-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 Lookup

sim-swap-lookup page anchor

SIM swap date and timestamp returned (paid)

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v2.phoneNumbers('+447772000001')
_10
.fetch({fields: 'sim_swap'})
_10
.then(phone_number => console.log(phone_number.simSwap));

Output

_28
{
_28
"calling_country_code": "44",
_28
"country_code": "GB",
_28
"phone_number": "+447772000001",
_28
"national_format": "07772 000001",
_28
"valid": true,
_28
"validation_errors": null,
_28
"caller_name": null,
_28
"sim_swap": {
_28
"last_sim_swap": {
_28
"last_sim_swap_date": "2020-04-27T10:18:50Z",
_28
"swapped_period": "PT48H",
_28
"swapped_in_period": true
_28
},
_28
"carrier_name": "Vodafone UK",
_28
"mobile_country_code": "276",
_28
"mobile_network_code": "02",
_28
"error_code": null
_28
},
_28
"call_forwarding": null,
_28
"line_status": null,
_28
"line_type_intelligence": null,
_28
"identity_match": null,
_28
"reassigned_number": null,
_28
"sms_pumping_risk": null,
_28
"phone_number_quality_score": null,
_28
"url": "https://lookups.twilio.com/v2/PhoneNumbers/+447772000001"
_28
}


Rate this page: