Phone Intelligence API

Overview

Filter and optimize with authority. Phone Intelligence request provides the metadata on a phone number. Using a RESTful GET API request, you’ll receive metadata attributes associated with the phone such as Is Valid, Is Connected, Country Code, Is Prepaid, Line Type, Carrier and more.

Get a free API key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/2.2/phone.json?phone_number=6464806649&api_key=KEYVAL

REQUEST PARAMETERS

PARAMETERSDESCRIPTIONEXAMPLES
api_keySee here to acquire an API key. REQUIRED
phone_numberContains a raw unparsed or a formatted phone number. REQUIRED

2069735184 or 12069735184 or 206-601-3561

country_hintContains the ISO-3166-1 alpha-2 code for the phone_number.

US or MX or ZA

Response

A Phone Intelligence response is formatted as follows:

Click the # to see that field used within the example JSON response.

Phone Intelligence Response

1idType

Copy
"id":{
"key":"Phone. 3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable",
"type":"Phone"
The entity id

2phone_numberString

Copy
"phone_number":"6464806649"
Complete undecorated phone number without extension or country code. Example: “2065551212”

3is_validBoolean

Copy
"is_valid":true
A boolean value indicating if the phone is a valid phone number and has been assigned to a carrier. Possible values are true, false or null.

4is_connectedBoolean

Copy
"is_connected":true
If false, this number is currently disconnected and cannot make/receive calls.

If true, this is a connected number.

If null, we do not have enough information to determine the current status of this phone.

5country_calling_codeString

Copy
"country_calling_code":"1"
International country code (Spec: ITU-T E.164). Example: “1” for USA & Canada

6line_typeString

Copy
"line_type":"NonFixedVOIP"
Line type can be any of the following:

  • Mobile: Wireless phone line
  • Landline: Traditional wired phone line
  • FixedVOIP: VOIP based fixed line phones tied to addresses (normally provided by cable companies like Comcast for instance)
  • NonFixedVOIP: Skype, Google Voice for example
  • Voicemail: Voicemail-only service
  • TollFree: Callee pays for call
  • Premium: Caller pays a premium for the call–e.g. 976 area code
  • Other: Anything that does not match the previous categories
  • Unknown: Line type cannot be determined
7carrierString

Copy
"carrier":"tw telecom"
The company that provides voice and/or data services for this phone number. Carriers are returned at the MVNO level.

8is_prepaidBoolean

Copy
"is_prepaid":false
If true, phone number is associated to a prepaid phone account

If false, phone number is not associated with a prepaid phone account

If null, the prepaid status of the phone is not known

Note: Certain attributes like is_connected and is_prepaid, are specific to North America only.

Example

Request

Copy
https://proapi.whitepages.com/2.2/phone.json?phone_number=6464806649&api_key=KEYVAL

Response

Copy
{
"results":[
{
"id":{
"key":"Phone. 3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable",
"type":"Phone",
},
"phone_number":"6464806649",
"is_valid":true,
"is_connected":true,
"country_calling_code":"1",
"line_type":"NonFixedVOIP",
"carrier":"tw telecom",
"is_prepaid":false
],
"messages":[]
}