Person Search

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:

Request

curl 'https://api.whitepages.com/v1/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:

Response

[
  {
    "id": "P1234567890",
    "name": "John Smith",
    "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": ["john.smith@example.com"],
    "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" }]
  }
]

Each record includes identifiers, addresses, phone numbers, emails, employment information, and linked property and relative records when available.

Understanding Phone Scores

Each phone number includes a score indicating relative confidence in the record's accuracy. A Higher score means that a number is more likely to be accurate than a lower score.

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`

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/v1/person?name=John%20Smith&zipcode=10001

Response 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.