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.
curl -X GET "https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}?Fields=sim_swap" \ -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
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 certain countries. |
SwappedPeriod |
An ISO-8601 duration representing a trailing time period, during which SwappedInPeriod indicates if the SIM was changed for the specified mobile phone number. Learn more about how to parse durations. |
SwappedInPeriod |
A boolean indicating whether the SIM was changed for the specified mobile phone number during the trailing SwappedPeriod. |
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.
