Person Search
Look up individuals by name, phone, or address
The Person Search API finds matching records in the Whitepages dataset based on name, location, phone number, or address. Use it to verify identities, find contact information, or enrich customer data.
Make Your First Request
Send a Request
Search for a person by name and location:
curl 'https://api.whitepages.com/v2/person?name=John%20Smith&city=New%20York&state_code=NY' \
--header 'X-Api-Key: YOUR_API_KEY'Replace YOUR_API_KEY with your actual API key.
Review the Response
A successful request returns matching person records:
[
{
"id": "P1234567890",
"name": "John Smith",
"score": 94,
"aliases": ["Johnny Smith", "J. Smith"],
"is_dead": false,
"current_addresses": [
{ "id": "A9876543210", "address": "123 Main St, New York, NY 10001" }
],
"historic_addresses": [
{ "id": "A1234567890", "address": "456 Oak Ave, Brooklyn, NY 11201" }
],
"owned_properties": [
{ "id": "R5432109876", "address": "123 Main St, New York, NY 10001" }
],
"phones": [{ "number": "(212) 555-0198", "type": "mobile", "score": 92 }],
"emails": [{ "address": "john.smith@example.com", "score": 88 }],
"date_of_birth": "1985-03-15",
"linkedin_url": "https://linkedin.com/in/johnsmith",
"company_name": "Acme Corp",
"job_title": "Software Engineer",
"relatives": [{ "id": "P0987654321", "name": "Jane Smith" }],
"result_metadata": {
"details_url": "/v2/person/P1234567890",
"phones": { "displayed": 1, "additional": 0 },
"emails": { "displayed": 1, "additional": 0 },
"historic_addresses": { "displayed": 1, "additional": 0 },
"owned_properties": { "displayed": 1, "additional": 0 }
}
}
]Each record includes identifiers, addresses, phone numbers, emails, employment information, and linked property and relative records when available, plus a result_metadata block summarizing each list and linking back to the canonical Person Details URL.
result_metadata
result_metadata.{list}.displayed is the count of items in the list on this
response; additional is the count of items linked to the person but not
included. Today additional is always 0. A future release will tune Person
Search to return a lean, ranked preview per list — the items most likely to
inform a match decision — with smaller payloads and more digestible results.
The full lists will always remain available at details_url (/v2/person/{id} ); additional is the forward-compatible signal for how many more entries
are there. Safe to begin parsing now.
Confidence Scores
Person records, phone numbers, and email addresses each include a score (0–100) indicating confidence of association. See Confidence Scores for details.
Request Parameters
Combine any of these parameters to refine your search:
| Parameter | Description | Example |
|---|---|---|
name | Full or partial name | John Smith |
first_name | First name | John |
middle_name | Middle name | Robert |
last_name | Last name | Smith |
phone | Phone number | 2125550198 |
street | Street address | 123 Main St |
city | City name | New York |
state_code | Two-letter state code | NY |
zipcode | ZIP code | 10001 |
min_age | Minimum age filter (18-65) | 25 |
max_age | Maximum age filter (18-65) | 55 |
include_historical_locations | Include historical addresses in search (default: false) | true |
include_fuzzy_matching | Enable fuzzy name matching (default: false) | true |
Query Parameter Behavior
The API uses AND logic, meaning all parameters must match. For example,
first_name=John will return records named John.
first_name=John&last_name=Smith will only return those same records that
also have the last name Smith.
Example with multiple parameters:
https://api.whitepages.com/v2/person?name=John%20Smith&zipcode=10001Response Codes
| Status | Description | Billable |
|---|---|---|
200 OK | Request successful | Yes |
400 Bad Request | Missing or invalid parameters | No |
403 Forbidden | Invalid API key | No |
404 Not Found | No matching record (by id) | Yes |
429 Too Many Requests | Rate limit exceeded | No |
5xx | Server error | No |
Note: A 200 OK status means the request was processed successfully, but
it doesn't guarantee results were found. Check the response body to see if any
records were returned.
Next Steps
Learn how to look up property ownership and resident data in the Property Search tutorial.
Related
Search for a person by name, phone number, and address
Retrieve person information with match scores and enriched emails.
Capability Map
Map a user's intent to the exact endpoint and parameters that answer it.
Reverse Phone Lookup
Find the owner of a phone number
Search by Address
Find people by current or historical addresses