WhitePages PRO API 2.0 Documentation

Our API provides five major services:

  • Find Person: search by a person’s name and location to find the person’s complete location and phone number.
  • Find Business: search by keywords and location to find a business’ complete location and phone number.
  • Reverse Phone: search by phone number to find related people and locations.
  • Reverse Location: search by street address to find related people and phone numbers.
  • Entity Retrieval: retrieve a person, business, address or phone by its WhitePages ID

The Contact Graph

The Contact Graph is how WhitePages represents its dataset. The contact 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 relations 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 Reverse Phone, Find Person, or Reverse Address API call.

For example, if you make a Reverse Phone request for the number 425-555-5555, you will be provided with a link to the information about the searched telephone number. From the telephone 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 contact graph is valid no matter how you enter it: from the telephone, address or 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. 

API Concepts

API Keys

WhitePages controls access to the API and data via an API Key. The API key is the primary data authentication method for your account. Additionally, usage is recorded and reported via the API Key. Your sales representative will provide you one or more keys to support your needs.

Security

Please take appropriate measures to protect access to your API keys as they give access to your paid account and if leaked could cause unauthorized usage to be attributed to your account. The API is provided via HTTP and HTTPS. We strongly recommend using HTTPS where possible to prevent third parties from acquiring your API key while in use.

Rates and Quotas

The API is metered and measured in two ways that matter to the customer, Rates and Quotas. Rates and quotas have been established for your account in the account setup phase. For more information, see your account documentation.

API Update Philosophy

The WhitePages API will be updated from time to time, and you should expect changes. We will work to minimize any changes which will require you to update your application, and breaking changes will be versioned appropriately.

New Fields

New fields are considered to be changes which do not require you to re-implement your solution. You should always develop your application using the WhitePages PRO dataset with the assumption that new fields may appear at any time, and that your application should not rely on the position of the data in the response to interpret its meaning. This allows us to continue to innovate and add features to the API in a way that developers can take advantage of them in the most flexible and rapid manner.

Semantic Changes and Field Removal

If the meaning of the data changes, the way that the data is represented changes or a field is removed from the dataset, this change is considered to be a change which might potentially render your application inoperable. This type of change will be made by updating the version of the API. The previous version of the API will be maintained for a period of time to allow developers to move to the new API version.

In general, it is good practice to upgrade to the latest version of the API soon after it is released. This will allow you to maintain your application with smaller changes and be in a better position to utilize new functionality, features and data as we roll them out.

The WhitePages PRO API Request

WhitePages ID

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

While WhitePages data is constantly maintained and updated by our systems, the WhitePages ID will continue to resolve to a specific record over time. If records are merged because the system identifies that those are the same record, each record’s WhitePages ID will continue to identify the merged record.

Durability

As described earlier, an instance of a primary type is identified by its WhitePages ID. Some instances do not exist in our core dataset but arise through calls to real-time data services. These instances are ephemeral, in that the values of their fields and their relations with other instances might change between requests to the WhitePages PRO API. Because of this, these IDs are generated on a per-request basis and do not persist between requests. To facilitate building applications which can provide differentiated behavior for durable and ephemeral IDs, the WhitePages ID type is actually a structure which contains a DurabilityType field. Legal values for this field are “Durable” and “Ephemeral”.

Request Format

Each search request consists of the following parts:

  1. The base URL, https://api.whitepages.com
  2. The version of the API you wish to target. This document covers version 2.0 of the WhitePages PRO API.
  3. The request retrieval type, any one of entity, person, phone, location or business
  4. The payload type specifier. The WhitePages PRO API 2.0 supports only JSON encoding of responses.
  5. The search parameters, which is an ampersand or semicolon separated list of parameter=value entries
  6. The API key parameter with your API key value.

Examples:

https://api.whitepages.com/2.0/phone.json?phone=2065551212&api_key=*KEYVAL*

https://api.whitepages.com/2.0/business.json?name=whitepages&zip=98101&api_key=*KEYVAL*

https://api.whitepages.com/2.0/person.json?last_name=Smith&zip=99163&api_key=*KEYVAL*

https://api.whitepages.com/2.0/location.json?street=1301%205th%20Ave&zip=98101&api_key=*KEYVAL*

https://api.whitepages.com/2.0/entity/Location.20908967-9a97-4375-94f7-a26cb243753b.json?api_key=*KEYVAL*

Note that KEYVAL is your API key value provided by WhitePages.

URL Parameters

Parameters can appear in any order. Parameter names are case-sensitive; parameter values are case-insensitive. For example “last_name=smith” matches “Smith”, but “Last_name=smith” is not a valid parameter assignment, since the parameter name is (all lower case) last_name and not (capitalized) Last_name.

Search TypeParameterRequired?DescriptionExamples
All api_key Yes
Person first_name Person’s first name
Person middle_name Could be name or initial
Person last_name Person’s surname
Person suffix Could restrict search to Jrs.
Person title Mr, Dr, etc.
Person,Business name Business or person name
Location, Person street_line_1 Number and street name of this location, if applicable 2808 Nero Blvd
Location, Person street_line_2 optional Apt 265
Location, Person city City in which this location exists, if applicable optional
Location, Person postal_code 5- or 9- digit US or 6-digit Canadian zipcode “92019” or “S3D 3F3”
Location, Person state_code 2 character state code “WA”
Location, Person country_code Normalized country code “US”
Location, Person address An unparsed address string “Seattle, WA”
Phone phone_number Contains a raw unparsed phone number. Only supports numeric characters. 2069735184 or 12069735184

Selection Parameters

In addition to the filter URL parameters, there are selection parameters that control the number and pagination of records returned.

FieldTypeDescriptionRequiredness
page_first number 0-based index of the first result to return. (i.e., if page_first = 2, and search finds results ordered a, b, c, d…, returns c, d…) optional
page_len number Number of results to return in search result (starting at page_first) optional
max_results number Maximum number of results to retrieve. Large numbers can significantly impact performance. optional

The WhitePages PRO API Response  

The WhitePages PRO API exposes search results by providing a subset of the WhitePages contact graph. By arranging data this way, the API minimizes duplication of data in the response and creates a minimal representation of the data required to answer the user’s request. The PRO API result is divided into the following sections.

{
	+ results: [...],
	+ dictionary {...}
}

The results array

The results array is the collection of the WhitePages IDs of the root entities that match the PRO API request. For a request which returns people, the results are a set of WhitePages IDs describing people. Similarly for locations, phone number and business searches, the WhitePages API returns locations, phone numbers and businesses.

results: [
	"Person.44475cd1-3575-4723-bed2-9a0fa2408444"
]

In this case, the result includes a single person ID.

The dictionary hash table

This dictionary hash table contains the record data matching the user’s request.

dictionary: {
	Person.44475cd1-3575-4723-bed2-9a0fa2408444: {...},
	Person.55582d45-0943-4f96-8ab3-c1fbaab70555: {...},
	Person.666aacb4-38af-41ac-9be6-0e53909bd666: {...},
	Location.7775e9d9-ebd7-434a-9b73-74e4bc74c777: {...},
	Location.888a9a13-d801-48ea-bd81-3087914b4888: {...},
	Phone.999f6fef-a2e0-4b08-cfe3-bc7128b7f999: {...}
}

The dictionary contains the information for the root person entities identified in the results array as well as all of the links (relations) that emanate from them. Nodes in the graph have a depth. The root entities have a depth of zero. The entities that are directly reachable from roots have a depth of one. The entities reachable from the depth one nodes have a depth of two. Only the entities with a graph depth of zero or one are fully materialized in the dictionary. Those at a depth of two have IDs that can be followed (through subsequent calls to the API), but these IDs do not have associated entries in the dictionary. The entity request can be used to follow links to entities outside of the dictionary data.

In your dictionary, you will find only four objects that represent the entirety of the WhitePages knowledge base. They are:

Error Response

If the API encounters an error you will receive a standard error message containing an error name and message.

{
	"error": {
		"name": "InvalidOptionsError",
		"message": "Invalid Options: last_nadme"
	}
}