New: pagination on person search, fuzzy matching, and more. See what's changed →
Whitepages Pro API
DocumentationReferencesChangelog
Person

Search for a person by name, phone number, and address

Retrieve person information with match scores and enriched emails. Raises ------ StrictMatchWithFuzzyMatchingError If ``strict_match`` and ``include_fuzzy_matching`` are both set to true — the two flags are semantically contradictory.

GET
/v2/person/

Authorization

ApiKeyAuth

x-api-key<token>

API key for authentication. Get your key from the Whitepages developer portal.

In: header

Query Parameters

phone?string

Phone number to search for

Match^(\+?1[-.\s]?)?\(?([0-9]{3})\)?[-.\s]?([0-9]{3})[-.\s]?([0-9]{4})$
Example"(216) 676-6366"
Example"216-676-6366"
Example"2166766366"
Example"+1-800-676-6366"
email?string

Email address to search for

Match^[^@\s]+@[^@\s]+\.[^@\s]+$
Example"user@example.com"
name?string

Full name or partial name match

Example"Marsha Mellow"
Example"Marsha"
Example"Mellow"
first_name?string

First name. Cannot be used with 'name'.

Example"Marsha"
Example"John"
middle_name?string

Middle name. Cannot be used with 'name'.

Example"Ann"
Example"Michael"
last_name?string

Last name. Cannot be used with 'name'.

Example"Mellow"
Example"Smith"
street?string

Street address including number and name

Example"123 Main St"
Example"Main Street"
city?string

Full city name

Example"Anytown"
Example"Seattle"
Example"Los Angeles"
state_code?string

2-Letter state code

Value in"AL" | "AK" | "AZ" | "AR" | "AS" | "CA" | "CO" | "CT" | "DE" | "DC" | "FL" | "GA" | "GU" | "HI" | "ID" | "IL" | "IN" | "IA" | "KS" | "KY" | "LA" | "ME" | "MD" | "MA" | "MI" | "MN" | "MS" | "MO" | "MT" | "NE" | "NV" | "NH" | "NJ" | "NM" | "NY" | "NC" | "ND" | "MP" | "OH" | "OK" | "OR" | "PA" | "PR" | "RI" | "SC" | "SD" | "TN" | "TX" | "TT" | "UT" | "VT" | "VA" | "VI" | "WA" | "WV" | "WI" | "WY"
Example"CA"
Example"NY"
Example"WA"
zipcode?string

Full 5-digit ZIP code

Match^\d{5}$
Example"94102"
Example"98101"
include_historical_locations?boolean

Include historical addresses in search

Examplefalse
Exampletrue
min_age?integer

Minimum age (18-65)

Range18 <= value <= 65
Example18
Example25
Example30
max_age?integer

Maximum age (18-65)

Range18 <= value <= 65
Example35
Example50
Example65
radius?number

Search radius in miles

Range0.1 <= value <= 100
Example2.5
Example5
Example10
include_fuzzy_matching?boolean

Enable fuzzy name matching to broaden search results

Examplefalse
Exampletrue
strict_match?boolean

Suppress automatic broadening. When true, the search does not fall back to fuzzy matching or radius expansion on a zero-result response; the exact query is authoritative.

Examplefalse
Exampletrue
page?integer

Page number (1-indexed)

Default1
Range1 <= value <= 10
Example1
Example2
Example3
page_size?integer

Number of results per page

Default15
Range1 <= value <= 15
Example5
Example10
Example15

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://api.whitepages.com/v2/person/"
{
  "results": [
    {}
  ],
  "metadata": {
    "result_count": 0,
    "page": 0,
    "page_size": 0
  }
}
{
  "error": {
    "code": 400,
    "message": "Bad Request",
    "long_message": "Invalid person ID format: 'sdf'. Person ID must start with 'P' followed by exactly 10 alphanumeric characters. Example: 'PABcd12345e' or 'P1234567890'.",
    "meta": null
  },
  "wp_trace_id": "3b0b537a60d84057817bb40563ca5c99"
}
{
  "message": "Forbidden"
}
{
  "error": {
    "code": 400,
    "message": "Short error message",
    "long_message": "The request was malformed",
    "meta": {
      "field": "email",
      "validation_error": "Invalid email format"
    }
  },
  "wp_trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "error": {
    "code": 400,
    "message": "Short error message",
    "long_message": "The request was malformed",
    "meta": {
      "field": "email",
      "validation_error": "Invalid email format"
    }
  },
  "wp_trace_id": "550e8400-e29b-41d4-a716-446655440000"
}
{
  "message": "Too Many Requests",
  "error": "usage_cap_exceeded",
  "error_instance_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "limit": 1000,
  "used": 1000,
  "reset_at": "2026-09-01T00:00:00+00:00",
  "upgrade_url": "https://www.whitepages.com/billing/manage-plan/pro-api"
}
{
  "error": {
    "code": 400,
    "message": "Short error message",
    "long_message": "The request was malformed",
    "meta": {
      "field": "email",
      "validation_error": "Invalid email format"
    }
  },
  "wp_trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Related

Person Search

Look up individuals by name, phone, or address

Capability Map

Map a user's intent to the exact endpoint and parameters that answer it.

Gets person details by id

Retrieve detailed person information by Whitepages person ID.

Authentication

Learn how to authenticate your requests to the Whitepages Pro API.

Rate Limits

Understand the rate limiting policies for the Whitepages Pro API, including monthly query limits and trial exhaustion.

Property V1 → V2

Field mapping and behavior changes when moving from /v1/property to /v2/property.

Gets person details by id GET

Retrieve detailed person information by Whitepages person ID.