Caller Identification API

Overview

Identify, prioritize, and connect with callers. Get an incoming caller’s full name, demographics, address data, and phone intelligence in real-time. Using a RESTful GET API request, you’ll receive a comprehensive overview on the incoming caller including phone metadata attributes, who is calling in and from where.

Get a free API key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.0/phone?api_key=API_KEY&phone=2069735100

Request Parameters

ParametersDescriptionExamples
api_keySee here to acquire an API key. REQUIRED
phoneContains a raw unparsed or a formatted phone number. The best way to provide phone number is E.164 formatREQUIRED

+12069735184
2069735184 or 12069735184 or 206-601-3561

Response

A Caller Identification response is formatted as follows.

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

Caller Identification Response

1phone_numberString

Copy
phone:"2069735184"
Complete undecorated input phone number without extension or country code

2is_validBoolean

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

3country_calling_codeString

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

4line_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
5carrierString

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

6is_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.

7is_commercialBoolean

Copy
is_commercial: false
If true, phone number is associated to a business. Possible values are true, false, null.

8belongs_toArray

Copy
belongs_to:[
{
name: "Whitepages",
age_range: null,
gender: null,
}
]
A list of people and/or business entities associated with this phone number.

9current_addressesArray

A list of unique current locations associated with people and businesses in belongs_to array. This will include:

  • Full Address including City, State, Postal Code
  • Lat/Long of the location
    • latitude - String - Decimal latitude
    • longitude - String - Decimal longitude
    • accuracy - Set - Represents the qualitative accuracy of the lat-long for the location. RoofTop, Street, PostalCode, City, State, Country.
  • Single/Multi-Unit, Is address active, etc.
10associated_peopleArray

A list of related and associated people to people and businesses in belongs_to array.

This will include

  • id
  • name of the associated person
  • relation: how this person related to phone owner
11alternate_phonesArray

This will include an array of alternate phone numbers for people and businesses in belongs_to array.

12warningsArray

An array of strings with validation warnings. For example “Invalid Input”

Note: Certain attributes like is_prepaid, is_commercial, associated location are specific to North America only. Coverage for belongs_to also is limited to US, Canada.

Example

Request

Copy
https://proapi.whitepages.com/3.0/phone?phone=2069735100&api_key=API_KEY

Response

Copy
{
phone_number: "2069735100",
is_valid: true,
country_calling_code: "1",
line_type: "NonFixedVOIP",
carrier: "tw telecom",
is_prepaid: false,
is_commercial: true,
belongs_to: [
{
name: "Whitepages Inc",
age_range: null,
gender: null
},
{
name: "Whitepages",
age_range: null,
gender: null
}
],
current_addresses: [
{
street_line_1: "1301 5th Ave",
street_line_2: "",
city: "Seattle",
postal_code: "98101",
zip4: "2603",
state_code: "WA",
country_code: "US",
lat_long: {
latitude: 47.608624,
longitude: -122.334442,
accuracy: "RoofTop"
},
is_active: null,
delivery_point: null
},
{
street_line_1: "1301 5th Ave Ste 1600",
street_line_2: "",
city: "Seattle",
postal_code: "98101",
zip4: "2625",
state_code: "WA",
country_code: "US",
lat_long: {
latitude: 47.608624,
longitude: -122.334442,
accuracy: "RoofTop"
},
is_active: true,
delivery_point: "MultiUnit"
}
],
associated_people: [ ],
alternate_phones: [
"8003361327"
],
warnings: [ ]
}