Lookup v2 API

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 are offering the following new data packages:

Pilot details

• 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.
• Access to SIM Swap and Call Forwarding information requires pre-approval from mobile network operators.
• Please take note of any pricing arrangements reached with your account manager during onboarding.

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)

To use the Lookup REST API in a non-US region you must do the following:

1. Create region-specific authentication credentials (see this quickstart for step-by-step)
2. Make a Lookup request to the region-specific FQDN

Currently, Lookup only supports the Ireland (IE1) Region outside of the US. As an example, to make a SIM Swap lookup and ensure processing and data residency in the EU, your request will resemble the request below with your $TWILIO_API_KEY and $TWILIO_API_KEY_SECRET resolving to the IE1 region API Key and Secret you created in Step 1.

curl -X GET \
'https://lookups.dublin.ie1.twilio.com/v2/PhoneNumbers/+447772000001?Fields=sim_swap' \
-u $TWILIO_API_KEY:$TWILIO_API_KEY_SECRET

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.

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.

Resource properties

The following properties are always returned: