Developer Documentation

Access comprehensive resources to help you integrate the power of Whitepages Pro into your application or service. Learn how to use our APIs, understand our approach to data and our proprietary data elements, and get inspiration for making the most of Whitepages Pro in your development efforts.

Get Your Free API Key

API Overview

Whitepages Pro API allows direct access to the most comprehensive and accurate data for people and businesses in North America, including the best mobile data available anywhere. Using a RESTful interface, the Whitepages Pro API allows flexible integration into your business systems via JSON. This protocol is simple to use and accessible from any common web programming language on any machine with Internet access.

How Data is Organized: The Identity Graph

The Identity Graph is how Whitepages Pro API represents its dataset. The identity graph is made up of four primary Whitepages types: Person, Business, Phone and Location. Instances of these types are connected by links which describe the relationships between them.

For example, John Smith lives with Jane Smith at 456 Elm Street in Bellevue, WA 98005 and his land-line telephone number is 425-555-5555. This information is available to the API, regardless of whether you make a Find Person , Reverse Phone, or Reverse Location Request.

For example, if you make a Reverse Phone Request for the number 425-555-5555, Whitepages Pro returns the record for the phone number. From the phone number you will follow a link to the address 456 Elm Street, Bellevue, WA 98005. That address contains two links, one to the person information for John Smith and one for the person information for Jane Smith.

This identity graph is valid no matter how you enter it: from the telephone, address, or any of the people, you will observe the same relations between the data and be presented with a similar graph. Only the entry points into the graph – the roots where you begin traversing the graph – will change.



Whitepages controls access to the API and data via an API Key. The API key is the primary data authentication method for your account. Also your usage is recorded and reported via the API Key. You can sign up for an API key here.

We strongly recommend using HTTPS where possible to prevent third parties from acquiring your API key while in use.

Whitepages ID

The Whitepages ID is a unique value which identifies each record (entity) in the Whitepages dataset. Whitepages IDs can be used to facilitate traversal of the records within a Whitepages Pro API response as well as beyond that response.

Whitepages IDs are made of three parts. First the type of ID, be it Person, Location, Business, or Phone is listed. Next is a UUID for the record. Last is the durability type for this record. Here is a sample of a Whitepages ID:




Durable Whitepages IDs persist within Whitepages databases and can be queried anytime. Ephemeral instances do not exist in our core dataset but arise through calls to 3rd party real-time data services. Their properties and relations with other instances might change between requests.

Pagination and Response Length

As part of the Whitepages API responses, you can control the number of records returned, as well as which record the return starts with, in the original GET request. For example you could start the results with the 9th record found for a location on a busy street, and then only the three records that follow it.



Data Structures

There are 4 data structures within Whitepages dataset. Based on the request and the response schema, one or more ID structures is returned as part of the response.


Phone ID Data Structure

Field Type Description
id ID The entity id. REQUIRED
line_type set Line type can be any of the following:

  • Landline: Traditional wired phone line
  • FixedVOIP: VOIP based fixed line phones
  • Mobile: Wireless phone line
  • Voicemail: Voicemail-only service
  • TollFree: Callee pays for call
  • Premium: Caller pays a premium for the call–e.g. 976 area code
  • NonFixedVOIP: Skype, for example
  • Other: Anything that does not match the previous categories
belongs_to data Entities (people or businesses) that share this phone number. More details on the Person or Business Id data structure can be found below.
associated_locations data Locations associated with this phone number. Landlines could be a physical address. Mobile numbers will give a less specific location. More details on the Location Id data structure can be found below.
is_valid boolean If false, this is an invalid phone number. Reasons include invalid or missing area code, invalid country code, invalid subscriber name, too short or too long number.
phone_number string Complete undecorated phone number without extension or country code. Example: “2065551212”
country_calling_code string International country code (Spec: ITU-T E.164). Example: “1” for USA & Canada
extension string The extension (numeric characters only) for the phone number. Example “143”
carrier string The company that provides voice and/or data services for this phone number. Example: “AT&T Wireless”
do_not_call boolean If true, for phone number is on the National Do Not Call Registry. Access to this data is restricted to customers who have signed an agreement agreeing to usage terms and conditions.
reputation Reputation of this phone number in a data structure. Higher the level/score for a number, worse its reputation and likelihood of it being a spam/risky number (e.g. Telemarketer, Robocalls, Toll free pumping, Phishing, etc.).

Field Type Description
level integer A 1-4 score on the likelihood of this number being spammy. 1 indicates high confidence that this number has not been associated with spam/risky behavior 4 indicates very high confidence that this is a spammy/risky number.
details An array of every spam/risky behavior this number has been associated with. Each array element consists of:

Field Type Description
score integer A 0-100 score on the likelihood of this number being associated with a particular type of spam or scam.
type string Type of behavior associated with this phone. Values are ‘not_spam’, ‘spam’ and ‘risk’ based on the behavior associated with the phone.
category Details on type of spam and risk associated with the phone. Examples include ‘robocall’, ‘toll free pumping’, ‘phishing’, etc.
volume_score integer A 1-4 score on how active the phone number has been making/receiving calls and sms.
report_count integer Number of reports we have received on this phone number being spam/risky.
is_prepaid boolean If true, phone number is associated to a prepaid phone account.
best_location ID The Whitepages id of the best location for this phone_number. More details on the Location Id data structure referenced can be found below.


Person ID Data Structure

Field Type Description
id ID The Whitepages entity id.
type Set Either “Full” or “LocationMember”. For “Full” all of the fields may be filled in. For “LocationMember”, the relations will be empty.
age_range string A string describing the persons age in a 5 year range, e.g. 30-34.
gender string Either “Male” or “Female”.
names data Name and alias data for this person. The names could include any of the following optional fields:

Name Fields Type Details
salutation string eg: Mr. Mrs, Dr.
first_name string
middle_name string
last_name string
suffix string
locations data Current and prior physical addresses for this entity. More details on the Location Id data structure can be found below.
phones data Current and historical land-line phones for this person. More details on the Phone Id data structure referenced can be found below.
best_name string A string representing the best name for this person.
best_location ID The id of the best location for this person.
valid_for data Date range the Person has been associated with phone or location.

Field Type Description
start data Day, Month and Year since when the Person has been associated with entity.
stop data Day, Month and Year we stopped associating this Person with entity. Null value indicates the link with phone/location is still active.
is_historical bool If true, this number has been associated with phone or location in the past. Otherwise, the person-phone/location association is active.


Address ID Data Structure

Field Type Description
id ID The Whitepages entity id.
type Set One of

  • LatLong
  • Address
  • State
  • City
  • County
  • Neighborhood
  • PostalCode
  • Country
  • ZipPlus4
  • CityPostalCode
legal_entities_at data Legal entities (people or businesses) that share this address. More details on the Person or Business Id data structure referenced can be found here.
city string Canonicalized city name. Example: “Olympia”.
postal_code string 5-digit US or 6 digit Canadian zipcode. Example: “92019” or “S3D 3F3”.
zip4 string 4-digit US zipcode extension. Example: “1020”.
state_code string 2 character US state/territory code (ISO 3166-2:US) or Canadian province code (ISO 3166-2:CA). Examples: “WA” for Washington State or “BC” for British Columbia.
country_code string Country code (ISO 3166-1 alpha-2), Example: “US”.
address string The complete street address, including both lines as appropriate. Example: “S 123 Huron Ave SE, Apt 1-A”.
house string House Number. Example: “123”.
street_name string Street Name. Example “Huron” in “135 NW Huron Ave”.
street_type string Canonical street type Example: “Ave” in “NW 45th Ave”.
pre_dir string Directional modifier preceding street name Example: “NW” in “NW 45th Str”.
post_dir string Directional modifier following a street type Example: “NW” in “3rd Ave NW”.
apt_number string Number of the apartment or suite Example: “1-A”.
apt_type string Canonical name of unit type Examples: “Ste”, “Apt”, “Unit”.
box_number string PO Box number. If this is not null, then the street_name will be “PO Box”. Example: “1231” in “PO Box 1231”.
standard_address_line1 string Canonicalized and validated address_line1. Contains both primary and the optional secondary address data. Primary address data is either a primary street address data (house_number, pre_dir, street_name, suffix, post_dir) or PO Box line. Secondary address data is apt_type and apt_nnumber. Example: “1301 5th Ave Ste 1600”.
standard_address_line2 string Not currently used. Intended to contain secondary address data.
standard_address_location string City/state/postal_code data. Example: “Seattle, WA 98101-2625”.
is_receiving_mail bool Only valid for US address LocationType. If true, then this indicates that the US Postal Service believes that mail delivered to that address will be collected. If false, then the not_receiving_mail_reason field will be set.
not_receiving_mail_reason set The reason why the is_receiving_mail field value is false. One of:

  • Vacant
  • NewConstruction
  • Rural
usage set Only valid for US address LocationType. This indicates the US Postal Service opinion about whether this address is primarily a “Business” or “Residential”.
delivery_point set Only valid for US address LocationType. Indicates to the US Postal Service whether deliver of mail requires special handling. One of:

  • CommercialMailDrop
  • POBoxThrowback
  • POBox
  • MultiUnit
  • SingleUnit
box_type set Only valid for US address LocationType. In conjunction with the delivery_point field, this provides additional information to the US Postal Service on how mail is received at this address. One of:

  • Facility
  • Contest
  • Detached
  • NonPersonnelUnit
  • School
  • Remittance
  • CallerService
address_type set Only valid for US address LocationType. In conjunction with the delivery_point and box_type fields, this provides additional information about the receiving mail address. One of:

  • Firm
  • GeneralDelivery
  • Highrise
  • POBox
  • RuralRoute
  • Street
lat_long Data Latitude, longitude and accuracy of this location in a data structure. For locations larger than addresses, this is the centroid of the location area.

Field Type Description
latitude string Decimal latitude
longitude string Decimal longitude
accuracy Set Represents the qualitative accuracy of the lat-long for the location. One of

  • RoofTop
  • Street
  • PostalCode
  • City
  • State
  • Country
is_deliverable bool Only valid for a LocationType “address”. Indicates whether the Postal Service can deliver mail to this address.


Business ID Data Structure

Field Type Description
id ID The Whitepages entity id.
name string Name for this business
locations data Current physical addresses for this entity. More details on the Location Id data structure referenced can be found below.
phones data Current phones for this person. More details on the Location Id data structure referenced can be found below.