Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Lookup v1 API


(warning)

Warning

Version 2 of the Lookup API is now available! Lookup v2 has an improved developer experience and exciting features, such as Twilio Regions support and these new data packages:

  • Line Type Intelligence : Get the line type of a phone number including mobile, landline, fixed VoIP, non-fixed VoIP, toll-free, and more.
  • SIM Swap : Get information on the last SIM change for a mobile phone number.
  • Call Forwarding : Get the unconditional call forwarding status of a mobile phone number.
  • Identity Match : Get confirmation of ownership for a mobile phone number by comparing user-provided information against authoritative phone-based data sources.

You are currently viewing Version 1 content. Lookup v1 will be maintained for the time being, but any new features and development will be on v2. We strongly encourage you to do any new development with Lookup v2. Check out the migration guide(link takes you to an external page) or the API v2 Reference for more information.

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(link takes you to an external page) for pricing information.


API URL

api-url page anchor

All URLs referenced in the documentation use the following URL.


_10
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(link takes you to an external page). 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.


HTTP requests to the REST API are protected with HTTP Basic authentication(link takes you to an external page). 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.


_10
curl -G https://lookups.twilio.com/v1/PhoneNumbers/{PhoneNumber} \
_10
-u '[YOUR ACCOUNT SID]:[YOUR AUTH TOKEN]'

You can find your account SID and auth token in your console(link takes you to an external page).

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 .


HTTP GET

http-get page anchor

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.

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:

URI parameters
PhoneNumbertype: stringPII MTL: 30 days
Path Parameter

The phone number to lookup in E.164(link takes you to an external page) format, which consists of a + followed by the country code and subscriber number.


CountryCodetype: stringPII MTL: 30 days
Query Parameter

The ISO country code(link takes you to an external page) of the phone number to fetch. This is used to specify the country when the phone number is provided in a national format.


Typetype: string[]Not PII
Query Parameter

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.


AddOnstype: string[]PII MTL: 30 days
Query Parameter

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(link takes you to an external page).


AddOnsDatatype: object<PREFIXED COLLAPSIBLE MAP ADDONS>Not PII
Query Parameter

Data specific to the add-on you would like to invoke. The content and format of this value depends on the add-on.

The following properties are always returned:

(warning)

Warning

  • 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
caller_nametype: objectPII MTL: 30 days

The name of the phone number's owner. If null, that information was not available.


country_codetype: stringPII MTL: 30 days

phone_numbertype: string<PHONE NUMBER>PII MTL: 30 days

The phone number in E.164(link takes you to an external page) format, which consists of a + followed by the country code and subscriber number.


national_formattype: stringPII MTL: 30 days

The phone number, in national format.


carriertype: objectNot PII

The telecom company that provides the phone number.


add_onstype: objectPII MTL: 30 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(link takes you to an external page).


urltype: string<URI>Not PII

The absolute URL of the resource.

(warning)

Warning

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

NameDescription
MobileCountryCodeThe three digit mobile country code of the carrier, used with the mobile network code to identify a mobile network operator.
MobileNetworkCodeThe 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).
NameThe name of the carrier; often subject to change.
TypeThe phone number type. Possible values are landline, mobile, or voip. See 'Phone Number Types' below for more information.
ErrorCodeThe error code, if any, associated with your request.

Phone Number Types

phone-number-type-values page anchor

The following are the possible values for the 'Type' property.

TypeDescription
landlineThe phone number is a landline number; generally not capable of receiving SMS messages.
mobileThe phone number is a mobile number; generally capable of receiving SMS messages.
voipAn 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.
nullThe phone number is valid but no information was returned from our data providers (see limitation for Canada numbers(link takes you to an external page)).

Caller name information

lookups-caller-name page anchor
(warning)

Warning

Caller name information is sourced through CNAM(link takes you to an external page) 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:

NameDescription
CallerNameString indicating the name of the owner of the phone number. If not available, this will return null.
CallerTypeString indicating whether this caller is a business or consumer. Possible values are BUSINESS, CONSUMER. If not available, this will return null.
ErrorCodeThe 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.


Carrier Lookup with E.164 Formatted Number

carrier-lookup-with-e164-formatted-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v1.phoneNumbers('+15108675310')
_10
.fetch({type: ['carrier']})
_10
.then(phone_number => console.log(phone_number.carrier));

Output

_15
{
_15
"caller_name": null,
_15
"carrier": {
_15
"error_code": null,
_15
"mobile_country_code": "310",
_15
"mobile_network_code": "456",
_15
"name": "verizon",
_15
"type": "mobile"
_15
},
_15
"country_code": "US",
_15
"national_format": "(510) 867-5310",
_15
"phone_number": "+15108675310",
_15
"add_ons": null,
_15
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
_15
}

Carrier Lookup with National Formatted Number

carrier-lookup-with-national-formatted-number page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v1.phoneNumbers('(510)867-5310')
_10
.fetch({countryCode: 'US', type: ['carrier']})
_10
.then(phone_number => console.log(phone_number.carrier));

Output

_15
{
_15
"caller_name": null,
_15
"carrier": {
_15
"error_code": null,
_15
"mobile_country_code": "310",
_15
"mobile_network_code": "456",
_15
"name": "verizon",
_15
"type": "mobile"
_15
},
_15
"country_code": "US",
_15
"national_format": "(510) 867-5310",
_15
"phone_number": "(510)867-5310",
_15
"add_ons": null,
_15
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
_15
}

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v1.phoneNumbers('+15108675310')
_10
.fetch({type: ['caller-name']})
_10
.then(phone_number => console.log(phone_number.callerName));

Output

_13
{
_13
"caller_name": {
_13
"caller_name": "Delicious Cheese Cake",
_13
"caller_type": "CONSUMER",
_13
"error_code": null
_13
},
_13
"carrier": null,
_13
"country_code": "US",
_13
"national_format": "(510) 867-5310",
_13
"phone_number": "+15108675310",
_13
"add_ons": null,
_13
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+15108675310"
_13
}


Using Add-ons with Lookup

using-add-ons-with-lookup page anchor

Lookup also supports Twilio Add-ons, enabling you to retrieve information from a multitude of 3rd party data sources, available via the Twilio Marketplace(link takes you to an external page).

You can add Lookup supported Add-ons by visiting the Twilio Console(link takes you to an external page) to enable the Add-on. Once it has been enabled, make sure you have 'Lookups' selected in its configuration:

Console screenshot showing that 'Lookups' is checked for the ekata_phone_valid Add-On.

When you use AddOns, you can pass additional parameters to the Add-on(s):

NameDescription
AddOns.addon_name.param_nameOptional. Passes additional data to the Add-on at request time. See Add-on documentation in Console(link takes you to an external page) to identify if the Add-on requires additional parameters.

Deterministic TCPA Compliance with Lookup and the Payfone Add-on

deterministic-tcpa-compliance-with-lookup-and-the-payfone-add-on page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_12
// Download the helper library from https://www.twilio.com/docs/node/install
_12
// Find your Account SID and Auth Token at twilio.com/console
_12
// and set the environment variables. See http://twil.io/secure
_12
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_12
const authToken = process.env.TWILIO_AUTH_TOKEN;
_12
const client = require('twilio')(accountSid, authToken);
_12
_12
client.lookups.v1.phoneNumbers('+16502530000')
_12
.fetch({addOns: ['payfone_tcpa_compliance'], addOnsData: {
_12
'payfone_tcpa_compliance.RightPartyContactedDate': '20160101'
_12
}, type: ['carrier']})
_12
.then(phone_number => console.log(phone_number.addOns));

Output

_37
{
_37
"caller_name": null,
_37
"country_code": "US",
_37
"phone_number": "+16502530000",
_37
"national_format": "(650) 253-0000",
_37
"carrier": {
_37
"mobile_country_code": null,
_37
"mobile_network_code": null,
_37
"name": "Level 3 Communications, LLC",
_37
"type": "landline",
_37
"error_code": null
_37
},
_37
"add_ons": {
_37
"status": "successful",
_37
"message": null,
_37
"code": null,
_37
"results": {
_37
"payfone_tcpa_compliance": {
_37
"status": "successful",
_37
"request_sid": "XRd3a2991c9108bde3ca9589ed84d31463",
_37
"message": null,
_37
"code": null,
_37
"result": {
_37
"Status": 0,
_37
"Response": {
_37
"MSISDNType": "NonFixedVoIP",
_37
"NumberMatch": "I",
_37
"VerifyNumberTransactionId": "2019459819"
_37
},
_37
"RequestId": "XRd3a2991c9108bde3ca9589ed84d31463",
_37
"Description": "Success."
_37
}
_37
}
_37
}
_37
},
_37
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+16502530000"
_37
}

Detect Robocallers with Lookup and Nomorobo Spam Score Add-on

detect-robocallers-with-lookup-and-nomorobo-spam-score-add-on page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_10
// Download the helper library from https://www.twilio.com/docs/node/install
_10
// Find your Account SID and Auth Token at twilio.com/console
_10
// and set the environment variables. See http://twil.io/secure
_10
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_10
const authToken = process.env.TWILIO_AUTH_TOKEN;
_10
const client = require('twilio')(accountSid, authToken);
_10
_10
client.lookups.v1.phoneNumbers('+19892008374')
_10
.fetch({addOns: ['nomorobo_spamscore']})
_10
.then(phone_number => console.log(phone_number.addOns));

Output

_32
{
_32
"caller_name": null,
_32
"country_code": "US",
_32
"phone_number": "+19892008374",
_32
"national_format": "(989) 200-8374",
_32
"carrier": {
_32
"mobile_country_code": "310",
_32
"mobile_network_code": null,
_32
"name": "Ytel/Blitz",
_32
"type": "mobile",
_32
"error_code": null
_32
},
_32
"add_ons": {
_32
"status": "successful",
_32
"message": null,
_32
"code": null,
_32
"results": {
_32
"nomorobo_spamscore": {
_32
"status": "successful",
_32
"request_sid": "XR763c8acc4c56d5e3e18d2f0f12345bc1",
_32
"message": null,
_32
"code": null,
_32
"result": {
_32
"status": "success",
_32
"message": "success",
_32
"score": 1
_32
}
_32
}
_32
}
_32
},
_32
"url": "https://lookups.twilio.com/v1/PhoneNumbers/+19892008374"
_32
}


Rate this page: