Menu

Expand
Rate this page:

Lookup v2 API

BETA

This API version is currently available as a Beta release and is fully capable of supporting production workloads. Some features are publicly available via self-service, while some are require carrier approvals and thus have gated access. Please see the table below for more details.

The Lookup API allows you to query information on a phone number so that you can make a trusted interaction with your user. The first version of the API allowed you to format and validate phone numbers (for free), as well as query additional Carrier and Caller information (pay per lookup).

In Lookup v2, we offer the following new data packages:

Package Description Coverage & Limitations Release Stage and Access
Line Type Intelligence Get the line type of a phone number including mobile, landline, fixed VoIP, non-fixed VoIP, toll-free, and more. Worldwide support; Canada requires special approval.

Public Beta: Available via self-service.

SIM Swap Get information on the last SIM change for a mobile phone number. Countries in Europe, Latin America, and North America. See coverage.

Private Beta: Requires carrier approvals; please submit form below to contact sales.

Call Forwarding Get the unconditional call forwarding status of a mobile phone number. Only numbers owned by major carriers in the United Kingdom are supported.

Private Beta: Requires carrier approvals; please submit form below to contact sales.

Lookup Mobile Intelligence Beta

Request Access

If you want access to the SIM Swap or Call Forwarding Private Beta, then submit the linked form. Access will be granted on a rolling basis.

API Base URL

All URLs referenced in the documentation use the following URL:

https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}

The Twilio REST API is served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

{PhoneNumber} is the phone number you are querying in E.164 or national format. If provided in national format, please also specify the country as an optional parameter. If no country is provided, this will default to US.

Authentication

HTTP requests to the REST API are protected with HTTP Basic authentication. To learn more about how Twilio handles authentication, please refer to our security documentation. In short, you will use your Twilio account SID as the username and your auth token as the password for HTTP Basic authentication.

curl -X GET \
'https://lookups.twilio.com/v2/PhoneNumbers/{PhoneNumber}' \
  -u '<YOUR_ACCOUNT_SID>:<YOUR_AUTH_TOKEN>'

You can find your account SID and auth token in the Console.

To learn more about authentication and interaction with the Twilio REST API, check out our documentation for requests to the API and Twilio’s response.

Regions support

To optimize application performance and control data residency, Lookup developers can select the Twilio Region that their Lookup request is processed out of. Twilio Lookup currently operates the following regions:

  • United States (US1) - default
  • Ireland (IE1)

Please see Using Lookup with Twilio Regions for more information.

Phone number lookup

HTTP GET

Returns phone number information matching the specified request. Formatting and base phone number validation information is included in the main body of every response. Line Type Intelligence, Caller Name, SIM Swap, Call Forwarding, and Live Activity fields can be optionally requested.

When requesting optional fields like Line Type Intelligence, Caller Name, SIM Swap, Call Forwarding, and Live Activity, you will incur charges on your account. Please double-check your code before running it so that you don't accidentally incur excessive unintended lookup charges.

Query parameters

The following basic GET query string parameters allow you to specify the phone number you want information about, along with fields of additional data.

Parameters in REST API format
phone_number
Path
get string PII MTL: 30 DAYS

The phone number to lookup in E.164 or national format. Default country code is +1 (North America).

fields
Optional
get string Not PII

A comma-separated list of fields to return. Possible values are caller_name, sim_swap, call_forwarding, live_activity, line_type_intelligence.

country_code
Optional
get string PII MTL: 30 DAYS

The country code used if the phone number provided is in national format.

Resource properties

The following properties are always returned:

Resource Properties in REST API format
calling_country_code
string Not PII

International dialing prefix of the phone number defined in the E.164 standard.

country_code

The phone number's ISO country code.

phone_number
phone_number PII MTL: 30 DAYS

The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.

national_format

The phone number in national format.

valid
boolean Not PII

Boolean which indicates if the phone number is in a valid range that can be freely assigned by a carrier to a user.

validation_errors
enum:validation_error[] Not PII

Contains reasons why a phone number is invalid. Possible values: TOO_SHORT, TOO_LONG, INVALID_BUT_POSSIBLE, INVALID_COUNTRY_CODE, INVALID_LENGTH, NOT_A_NUMBER.

caller_name

An object that contains caller name information based on CNAM.

sim_swap
object Not PII

An object that contains information on the last date the subscriber identity module (SIM) was changed for a mobile phone number.

call_forwarding
object Not PII

An object that contains information on the unconditional call forwarding status of mobile phone number.

live_activity
object Not PII

An object that contains live activity information for a mobile phone number.

line_type_intelligence
object Not PII

An object that contains line type information including the carrier name, mobile country code, and mobile network code.

url
url Not PII

The absolute URL of the resource.

Only valid numbers (for a given region, using length, and prefix information) will return formatting and validation results. If you attempt to lookup a phone number which is invalid, you will receive valid:false in the response. In some cases you will also receive a reason for the validation failure in the validation_errors field.

Access to Canada Line Type Intelligence and carrier information requires special approval. Please read this support article to learn more. Querying a Canada phone number without access will return a 60101 error.

The following additional properties are returned if you requested carrier information in your GET request:

Name 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 (only returned for mobile numbers).
CarrierName The name of the carrier; subject to change.
Type The phone number type. See Phone number type values for possible values.
ErrorCode The error code, if any, associated with your request.
Phone number type values

Carrier data is not available for phone number types: personal, tollFree, premium, sharedCost, uan, voicemail, pager, or unknown. In these cases MobileCountryCode, MobileNetworkCode, and CarrierName values will be null.

The following are the possible values for the Type property.

Type Description
landline The phone number is a landline number; generally not capable of receiving SMS messages.
mobile The phone number is a mobile number; generally capable of receiving SMS messages.
fixedVoip A virtual phone number associated with a physical device (e.g., Comcast or Vonage).
nonFixedVoip A virtual phone number that can be obtained on the internet without the need for a physical device (e.g., Google Voice or Enflick).
personal A phone number designated for personal use.
tollFree A toll-free phone number, which is one where calls are free for the calling party.
premium A premium rate phone number, which typically charges higher than normal rates for special services.
sharedCost A shared cost phone number, which is one where the charge is partially paid by the calling party and charges higher than normal rates.
uan A universal access number, which is a national number which can route incoming calls to different destinations.
voicemail A phone number associated with a voicemail service.
pager A phone number associated with a pager device.
unknown A valid phone number, but the line type could not be determined.

Caller name information is sourced through CNAM and only available for phone numbers owned by carriers in the US.

The following additional properties are returned if you requested caller_name in your GET request:

Property Description
CallerName A string indicating the name of the owner of the phone number. If not available, this will be null.
CallerType A string indicating whether this caller is a business or consumer. Possible values are BUSINESS and CONSUMER. If not available, this will be null.
ErrorCode The error code, if any, associated with your request.

Caller name lookups are billed per lookup, even if data is not available. Requesting a caller name lookup for international numbers will return null values, but will not be billed.

SIM swap information requires pre-approval from mobile network operators prior to gaining access and is supported in select countries. Please check out Lookup SIM Swap Overview for more information.

The following additional properties are returned if you requested sim_swap in your GET 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.
ErrorCode The error code, if any, associated with your request.

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.

Last SIM swap object

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.

Call forwarding information requires pre-approval from mobile network operators prior to gaining access and is only supported in the United Kingdom.

The following additional properties are returned if you requested call_forwarding in your GET 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.
CallForwardingStatus A boolean value indicating unconditional call forwarding is currently enabled for the requested mobile phone number (true) or is not (false).
ErrorCode The error code, if any, associated with your request.

Call forwarding lookups are billed per lookup, even if data may not be available. Currently, requesting call forwarding lookups for unsupported carriers will return null values, but will not be billed.

Live activity information

Get the connectivity status, porting, and roaming information of a mobile phone number.

Live Activity is in PILOT

  • The pilot phase is a tightly controlled release. Participants should prepare for possible service instability, API changes, or defects. It is not recommended that mission-critical applications depend on the availability of the service. However, all data is queried from live and accurate sources.
  • Live Activity is not supported in the US; access to Canada information requires special approval. Otherwise, it is generally supported worldwide, but may not return data from every network. Please conduct tests to confirm coverage for your desired country and network.
  • Information is returned as-is from mobile network operators' HLR and thus we do not provide any assurance on its accuracy.

The following additional properties are returned if you requested live_activity in your GET request:

Property Description
Connectivity The connectivity status of the requested mobile phone number. See Connectivity status values below.
Ported A boolean value indicating the requested mobile phone number has been ported (true) or has not (false).
PortedCarrier If ported is true, this contains carrier information for the network the number was ported to.
Roaming Boolean indicating whether or not the requested mobile phone number is roaming.
RoamingCarrier If roaming is true, this contains carrier information for the network the number is roaming in.
OriginalCarrier If ported is false, this contains carrier information for the number's current network. If ported is true, this contains carrier information for the network the number was ported from.
ErrorCode The error code, if any, associated with your request.
Connectivity status values

The following are the possible values for the Connectivity property.

Value Description
connected Indicates that the number is valid and the target handset is currently connected to the mobile network and reachable.
absent Indicates that the number is valid but the target handset is currently switched off or out of network reach.
invalid Indicates that the number is not currently assigned to any subscriber on the mobile network or is invalid.
undetermined Indicates that the connectivity status could not be determined and the connectivity status is unknown. This can be caused by lack of connectivity to the target network operator or other exceptions and errors.
Carrier objects

The following properties are returned in the PortedCarrier, RoamingCarrier, and OriginalCarrier objects.

Value 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.
Name The name of the carrier.
Country The carrier's ISO country code. This property is only returned in the RoamingCarrier object.
        
        
        
        Valid E.164 phone number (free)

        Formatting and Validation Lookup

        Valid E.164 phone number (free)
              
              
              
              Invalid phone number that is too long (free)

              Formatting and Validation Lookup

              Invalid phone number that is too long (free)
                    
                    
                    
                    Valid nonFixedVoip phone number (paid)

                    Line Type Intelligence Lookup

                    Valid nonFixedVoip phone number (paid)
                          
                          
                          
                          Caller name with consumer type (paid)

                          Caller Name Lookup

                          Caller name with consumer type (paid)
                                
                                
                                
                                SIM swap date and timestamp returned (paid)

                                SIM Swap Lookup

                                SIM swap date and timestamp returned (paid)
                                      
                                      
                                      
                                      Call forwarding enabled (paid)

                                      Call Forwarding Lookup

                                      Call forwarding enabled (paid)
                                            
                                            
                                            
                                            Mobile phone number with connected status (paid)

                                            Live Activity Lookup

                                            Mobile phone number with connected status (paid)
                                                  
                                                  
                                                  
                                                  Connected status with ported response (paid)

                                                  Live Activity Lookup with Ported Response

                                                  Connected status with ported response (paid)
                                                        
                                                        
                                                        
                                                        Connected status with roaming response (paid)

                                                        Live Activity Lookup with Roaming Response

                                                        Connected status with roaming response (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.

                                                              
                                                              
                                                              

                                                              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!

                                                              Refer us and get $10 in 3 simple steps!

                                                              Step 1

                                                              Get link

                                                              Get a free personal referral link here

                                                              Step 2

                                                              Give $10

                                                              Your user signs up and upgrade using link

                                                              Step 3

                                                              Get $10

                                                              1,250 free SMSes
                                                              OR 1,000 free voice mins
                                                              OR 12,000 chats
                                                              OR more