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. Twilio will use libphonenumber, Google’s open source phone number handling library, to properly format possible phone numbers for a given region, using length and prefix.

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.

Lookup a Phone Number

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:

Names in PHP format
`phoneNumber` Required	get phone_number PII MTL: 60 DAYS The phone number to lookup in E.164 format, which consists of a + followed by the country code and subscriber number.
`countryCode` Optional	get string PII MTL: 60 DAYS 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	get string[] Not PII The type of information to return. Can be: `carrier` or `caller-name`. The default is null. Carrier information costs $0.005 per phone number looked up. Caller Name information is currently available only in the US and costs $0.01 per phone number looked up. To retrieve both types on information, specify this parameter twice; once with `carrier` and once with `caller-name` as the value.
`addOns` Optional	get string[] PII MTL: 60 DAYS The `unique_name` of an Add-on you would like to invoke. Can be the `unique_name` of an Add-on that is installed on your account. You can specify multiple instances of this parameter to invoke multiple Add-ons. For more information about Add-ons, see the Add-ons documentation.
`addOnsData` Optional	get prefixed_collapsible_map<AddOns> Not PII 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:

Names in PHP format
`callerName`	string_map PII MTL: 60 DAYS The name of the phone number's owner. If `null`, that information was not available.
`countryCode`	string PII MTL: 60 DAYS The ISO country code for the phone number.
`phoneNumber`	phone_number PII MTL: 60 DAYS The phone number in E.164 format, which consists of a + followed by the country code and subscriber number.
`nationalFormat`	string PII MTL: 60 DAYS The phone number, in national format.
`carrier`	string_map Not PII The telecom company that provides the phone number.
`addOns`	object PII MTL: 60 DAYS A JSON string with the results of the Add-ons you specified in the `add_ons` parameters. For the format of the object, see Using Add-ons.
`url`	url Not PII The absolute URL of the resource.

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 cannot exist, you will receive an HTTP 404 error.

Carrier Information

NOTE: For some regions like Canada, we are unable to return carrier and cellphone data by default. Please contact our support team to switch on those regions. More information is available on our support site.

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

Name	Description
MobileCountryCode	The mobile country code of the carrier (for mobile numbers only).
MobileNetworkCode	The mobile network code of the carrier (for mobile numbers only).
Name	The name of the carrier. Please bear in mind that carriers rebrand themselves constantly and that the names used for carriers will likely change over time.
Type	The phone number type. Possible values are `landline`, `mobile`, or `voip`. See 'Phone Number Type' 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.

Caller Name

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.

Note that Caller Name lookups for US numbers are billed per lookup, even if data may not be available. Currently, requesting Caller Name Lookup for international numbers will return null values, but will not be billed.

Examples

Loading Code Sample...

Output

Look up a phone number in the E.164 format

Carrier Lookup with E.164 Formatted Number

Look up a phone number in the E.164 format

Loading Code Sample...

Output

Carrier Lookup with National Formatted Number

Loading Code Sample...

Output

Caller Name Lookup

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:

Enable Lookups to use your whitepages pro add-on

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

Loading Code Sample...

Output

Get additional caller information with Lookup and Whitepages Pro Caller ID Add-on

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.

Loading Code Sample...

Output

Look up a phone number including the Payfone TCPA Compliance Add-on results.

Deterministic TCPA Compliance with Lookup and the Payfone Add-on

Look up a phone number including the Payfone TCPA Compliance Add-on results.

Loading Code Sample...

Output

Detect Robocallers with Lookup and Nomorobo Spam Score Add-on

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 browsing the Twilio tag on Stack Overflow.

Loading Code Sample...

Output