WhitePages.com API Documentation

The WhitePages.com API is a RESTful interface in which simple HTML GET requests are used to access the API. The WhitePages.com API will provide XML responses by default. Optionally, the response format can be specified as JSON if desired. Other formats may be supported in the future. This protocol is simple to use and accessible from any common web programming language on any machine with internet access.

The following API functions are available in this release:

find_person - Retrieves contact information about a person, such as a telephone number and address
reverse_phone - Retrieves contact information about a telephone number
reverse_address - Retrieves contact information about the people at an address

Registration Required

Please note that before using the WhitePages.com API you must register and be issued an API key. The API key will be attached to each query you send to the API. For more information about registration, see the section: Getting Started. Limit one API key per person.

Request Format

Each search request consists of the following parts:

The base URL, http://api.whitepages.com/
The search type, either find_person, reverse_phone, or reverse_address
The API version, currently 1.0
The search parameters, which is a semicolon separated list of parameter=value entries
The API key parameter with your API key value, which is the unique identifier you received when you registered.

For example, to search for the person "Mike Smith" in Seattle, the request would look like:

http://api.whitepages.com/find_person/1.0/?firstname=mike;lastname=smith;zip=98101;api_key=API_KEYVAL

where API_KEYVAL is your API key value.

About the Response

There are four categories of search responses:

The results response - response with one or more search results records.
The no results response - response when no search result records were found.
The request for clarification response - response when a search was ambiguous and needs clarification, most commonly when a location such as a city is incompletely described in the search request. A list of possible alternatives is provided in this response.
The error response - response with an error message, such as a required parameter was missing.

Each of these responses share a common Data Dictionary which describes the elements that may be returned by the WPAPI.

Links in the Response

A successful search response will also include some links which can be used for more detailed information. The specific links returned will depend on the search type and the results. Each link returned will include a description, a text field which describes the link and is suitable for display, and the URL of the link. These links will be chosen from among:

View Map: displays a map of the address.
Driving Directions: displays a map of the address and provides a way to get driving directions to the address.
View Listing Details: displays information about the person, such as Web results, public records, and professional profiles.
View All Results: displays additional listings if more listing were found beyond the API search limits.
View Work Listings: displays only work listings, but may be convenient if some work and some residential listings were found.
Find Neighbors: displays information about the address, such as Web results, neighbors, and nearby businesses.
View Search Suggestions: displays some alternate suggestions for searches which returned no results.
WhitePages.com: links to the home page of WhitePages.com

Response Format

The XML response returned by the API conforms to this XSD.

Frequently Asked Questions

Answers to some frequently asked questions about the WhitePages.com API may be found in the FAQ.