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, 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/3.0/phone_intel?phone=6464806649&api_key=KEYVAL

REQUEST PARAMETERS

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

2069735184 or 12069735184 or 206-601-3561

phone.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

1idString

Copy
"id": "Phone.3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable"
Id of the phone number in the request.

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 valid. Possible values are true, false or null.

4country_calling_codeString

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

5country_codeString

Copy
"country_code":"US"
Alpha-2 country code. Example: “US” for United States, “DE” for Germany.

6country_nameString

Copy
"country_code":"United States"
Full country name.

7line_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: Google Voice for example
  • Voicemail: Voicemail-only service
  • TollFree: Call recipient 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
8carrierString

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

9is_prepaidBoolean

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

If false, phone number is not associated with a prepaid phone carrier.
If null, the prepaid status of the phone is not known.

Note: is_prepaid is available in North America only.

10errorObject
Copy
"error": null

An error object which contains name string and message string. For example:

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}

OR

Copy
{
"message": "International Phone Number Lookup not authorized",
"name": "AuthError"
}
11warningsArray
Copy
"warnings": []

An array containing one or more of the following warning message strings:

  • Invalid Input
  • Missing Input
  • Invalid country_hint value. Only Alpha-2 and Alpha-3 supported

Response

Copy
{
"id": "Phone.3df36fef-a2e1-4b08-cfe3-bc7128b702aa.Durable",
"phone_number": "6464806649",
"is_valid": true,
"country_calling_code": "1",
"country_code": "US",
"country_name": "United States",
"line_type": "NonFixedVOIP",
"carrier": "Twilio",
"is_prepaid": null,
"error": null,
"warnings": [ ]
}