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",
"aliases": ["Johnny Smith", "J. Smith"],
"is_dead": false,
"age": 40,
"date_of_birth": "1985-03-15",
"linkedin_url": "https://linkedin.com/in/johnsmith",
"company_name": "Acme Corp",
"job_title": "Software Engineer",
"match_score": 94,
"matched_by": ["name", "address"],
"phones": [{ "number": "(212) 555-0198", "type": "mobile", "score": 92 }],
"current_addresses": [
{
"address_id": "A9876543210",
"full_address": "123 Main St, New York, NY 10001",
"line1": "123 Main St",
"city": "New York",
"state": "NY",
"zip": "10001"
}
],
"historic_addresses": [
{
"address_id": "A1234567890",
"full_address": "456 Oak Ave, Brooklyn, NY 11201",
"line1": "456 Oak Ave",
"city": "Brooklyn",
"state": "NY",
"zip": "11201"
}
],
"owned_properties": [
{ "id": "R5432109876", "address": "123 Main St, New York, NY 10001" }
],
"emails": [{ "email": "john.smith@example.com", "score": 88 }],
"relatives": [{ "id": "P0987654321", "name": "Jane Smith" }],
"result_metadata": {
"details_url": "/v2/person/P1234567890",
"phones": { "displayed": 1, "additional": 3 },
"emails": { "displayed": 1, "additional": 0 },
"historic_addresses": { "displayed": 1, "additional": 5 },
"owned_properties": { "displayed": 1, "additional": 0 }
}
}
]Each record includes identifiers, contact and employment fields, match signals, address and phone lists, and a result_metadata block summarizing each list and linking to the full Person Details record.
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 that were
not included because the list is capped (phones: 4, emails: 3, historic
addresses: 5, owned properties: 5). The full lists are always available via
details_url at /v2/person/{id}.
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 | Force fuzzy name matching on the first pass. When false (default) the API runs exact match first and falls back to fuzzy automatically if the exact pass returns no results. See Fuzzy Matching. | true |
strict_match | Suppress automatic fuzzy fallback (default: false). When true, a zero-result exact query is returned as-is instead of retrying with fuzzy matching. Cannot be combined with include_fuzzy_matching=true. | 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. Raises ------ StrictMatchWithFuzzyMatchingError If ``strict_match`` and ``include_fuzzy_matching`` are both set to true — the two flags are semantically contradictory.
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