Menu

Expand
Rate 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.

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.
Loading Code Sample...
        
        
        SIM swap date and timestamp returned (paid)

        SIM Swap Lookup

        SIM swap date and timestamp returned (paid)
        Rate this page:

        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.

        Loading Code Sample...
              
              
              

              Thank you for your feedback!

              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

              Sending your feedback...
              🎉 Thank you for your feedback!
              Something went wrong. Please try again.

              Thanks for your feedback!

              thanks-feedback-gif