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 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. See SIM Swap Overview for more information. Countries in Europe, Latin America, and North America. See coverage.

Private Beta: Requires carrier approvals; please submit this form 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 this form to contact sales.

Live Activity

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

Worldwide support except for the US; Canada requires special approval. May not return data from every network.

Pilot: To request access, submit this form.

Identity Match

Get confirmation of ownership for a mobile phone number by comparing user-provided information against authoritative phone-based data sources.

Countries in Europe, Latin America, North America, and Australia. Requires carrier approvals for certain countries. See full coverage details here.

Pilot: To request access, submit this form.

Caller Name

Get information on the caller name and type for a mobile phone number.

Only numbers owned by carriers in the US are supported.

General Access: Available via self-service.

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, identity_match.

country_code
Optional
get string PII MTL: 30 DAYS

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

first_name
Optional
get string Not PII

User’s first name. This query parameter is only used (optionally) for identity_match package requests.

last_name
Optional
get string Not PII

User’s last name. This query parameter is only used (optionally) for identity_match package requests.

address_line_1
Optional
get string Not PII

User’s first address line. This query parameter is only used (optionally) for identity_match package requests.

address_line_2
Optional
get string Not PII

User’s second address line. This query parameter is only used (optionally) for identity_match package requests.

city
Optional
get string Not PII

User’s city. This query parameter is only used (optionally) for identity_match package requests.

state
Optional
get string Not PII

User’s country subdivision, such as state, province, or locality. This query parameter is only used (optionally) for identity_match package requests.

postal_code
Optional
get string Not PII

User’s postal zip code. This query parameter is only used (optionally) for identity_match package requests.

address_country_code
Optional
get iso_country_code Not PII

User’s country, up to two characters. This query parameter is only used (optionally) for identity_match package requests.

national_id
Optional
get string PII MTL: 30 DAYS

User’s national ID, such as SSN or Passport ID. This query parameter is only used (optionally) for identity_match package requests.

date_of_birth
Optional
get string PII MTL: 30 DAYS

User’s date of birth, in YYYYMMDD format. This query parameter is only used (optionally) for identity_match package requests.

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.

identity_match
object Not PII

An object that contains identity match information. The result of comparing user-provided information including name, address, date of birth, national ID, against authoritative phone-based data sources

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.

        
        
        
        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)
              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!

                    thanks-feedback-gif