Person Search API
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-00",
"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": 0 },
"emails": { "displayed": 1, "additional": 0 },
"historic_addresses": { "displayed": 1, "additional": 0 },
"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 |
email | Email address | john@example.com |
street | Street address | 123 Main St |
city | City name | New York |
state_code | Two-letter state code | NY |
zipcode | ZIP code | 10001 |
radius | Search radius in miles (max 100) around the address, city, or ZIP code. See Search by Radius. | 10 |
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 |
page | Page number, 1-indexed (default: 1). See Pagination. | 2 |
page_size | Results per page, 1-15 (default: 15). See Pagination. | 15 |
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 API tutorial.
Related
Search for a person by name, phone number, and address
Retrieve person information with match scores and enriched emails. `strict_match` and `include_fuzzy_matching` are contradictory, so enabling both on one request is rejected. Either alone is fine, and so is sending both with one of them false.
Capability Map
Map a user's intent to the exact endpoint and parameters that answer it.
Reverse Phone Lookup API
Find the people who match a phone number, ranked by confidence
Search by Address
Find people by current or historical addresses
Search by Radius
Find people within a specified distance of a location
Pagination
Page through person search results using the page and page_size parameters