Lookup API
The Lookup API provides a way to retrieve additional information about a phone number. Lookup currently supports the following types of data.
- Region-specific number formatting and validation
- Carrier Information
- Caller Name
You can specify one or more types of information you would like to purchase in the request, check the Lookup Product Page for pricing information.
API URL
All URLs referenced in the documentation use the following URL.
https://lookups.twilio.com/v1/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 requesting information about. Phone numbers can be specified either in national formatting or in standard E.164 format. If providing a number in local 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 -G https://lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber} \
-u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'You can find your account SID and auth token in your 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.
Phone number lookup
HTTP GET
Returns phone number information matching the specified request. Formatting information is standard. Carrier, Caller Name, and phone number type information can be requested, in addition to using Add-ons to access 3rd party data sources.
Query Parameters
The following basic GET query string parameters allow you to specify the phone number you want information about and the types of information you’d like:
| Parameters in REST API format | |
|---|---|
phone_number
Path
|
The phone number to lookup in E.164 format, which consists of a + followed by the country code and subscriber number. |
country_code
Optional
|
The ISO country code of the phone number to fetch. This is used to specify the country when the phone number is provided in a national format. |
type
Optional
|
The type of information to return. Can be: |
add_ons
Optional
|
The |
add_ons_data
Optional
|
Data specific to the add-on you would like to invoke. The content and format of this value depends on the add-on. |
Resource Properties
The following properties are always returned:
- Only possible numbers (for a given region, using length and prefix information) will return formatting results. If you attempt to lookup a phone number which is not valid, you will receive an HTTP 404 error.
- Machine to machine (M2M) phone numbers are not supported in Lookup and will return an HTTP 404 error.
| Resource Properties in REST API format | |
|---|---|
caller_name
|
The name of the phone number's owner. If |
country_code
|
The ISO country code for the phone number. |
phone_number
|
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. |
carrier
|
The telecom company that provides the phone number. |
add_ons
|
A JSON string with the results of the Add-ons you specified in the |
url
|
The absolute URL of the resource. |
- Access to Canada 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.
- Toll free numbers do not return carrier data, but will return a valid HTTP response.
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). |
| Name | The name of the carrier; often subject to change. |
| Type | The phone number type. Possible values are landline, mobile, or voip. See 'Phone Number Types' below for more information. |
| ErrorCode | The error code, if any, associated with your request. |
Phone Number Types
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. |
| voip | An internet based phone number that may or may not be capable of receiving SMS messages. For example, Google Voice. Returned for U.S. numbers only. |
| null | The phone number is valid but no information was returned from our data providers (see limitation for Canada numbers). |
Caller name information
Caller name information is sourced through CNAM and only available for phone numbers owned by carriers in the US. We recommend testing the coverage rate of this lookup with your specific dataset of phone numbers.
The following additional properties are returned if you requested caller name in your GET request:
| Name | Description |
|---|---|
| CallerName | String indicating the name of the owner of the phone number. If not available, this will return null. |
| CallerType | String indicating whether this caller is a business or consumer. Possible values are BUSINESS, CONSUMER. If not available, this will return null. |
| ErrorCode | The error code, if any, associated with your request. |
Caller name lookups for US numbers are billed per lookup, even if data is not be available. Requesting Caller name lookups for non-US will return null values and will not be billed.
Using Add-ons with Lookup
Lookup also supports Twilio Add-ons, enabling you to retrieve information from a multitude of 3rd party data sources, available via the Twilio Marketplace.
You can add Lookup-supported add-ons by visiting the Twilio console to enabling the add-on, making sure you have 'Lookups' selected:
When you use AddOns, you can pass additional parameters to the Add-on(s):
| Name | Description |
|---|---|
| AddOns.addon_name.param_name | Optional. Passes additional data to the Add-on at request time. See Add-on documentation in Console to identify if the Add-on requires additional parameters. |
Examples with Add-ons
Whitepages Pro Caller ID geographic restrictions
Please note that the Whitepages add-on only works with phone numbers with the +1 country code: U.S., Canada, Puerto Rico. If you need to check numbers in all countries, consider using our Lookup API without add-ons, which you can try out in the console.
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 Community Forums or browsing the Twilio tag on Stack Overflow.