Reverse Phone Lookup
Find the owner of a phone number
Use the phone parameter to perform a reverse phone lookup and identify who owns a phone number. This returns person records associated with the phone number, including their name, address, and other contact information.
Basic Usage
Look up a phone number:
curl 'https://api.whitepages.com/v2/person?phone=2065550198' \
--header 'X-Api-Key: YOUR_API_KEY'This returns person records associated with the phone number.
Parameters
| Parameter | Type | Description |
|---|---|---|
phone | string | Phone number to look up |
Examples
Basic Phone Lookup
Find who owns a phone number:
curl 'https://api.whitepages.com/v2/person?phone=2125550198' \
--header 'X-Api-Key: YOUR_API_KEY'Combine with Name for Verification
Verify that a phone number belongs to a specific person:
curl 'https://api.whitepages.com/v2/person?phone=2125550198&name=John%20Smith' \
--header 'X-Api-Key: YOUR_API_KEY'Combine with Location
Narrow results by adding location filters:
curl 'https://api.whitepages.com/v2/person?phone=2125550198&state_code=NY' \
--header 'X-Api-Key: YOUR_API_KEY'Use Cases
Reverse phone lookup is useful for verifying caller identity, confirming contact information accuracy, and enriching customer records with additional details.
Response
The response includes the phone owner's information along with all associated contact details:
[
{
"id": "P1234567890",
"name": "John Smith",
"aliases": ["Johnny 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": 95,
"matched_by": ["phone"],
"phones": [
{ "number": "(212) 555-0198", "type": "mobile", "score": 95 },
{ "number": "(212) 555-0199", "type": "landline", "score": 72 }
],
"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": [],
"emails": [{ "email": "john.smith@example.com", "score": 88 }],
"relatives": [{ "id": "P0987654321", "name": "Jane Smith" }],
"result_metadata": {
"details_url": "/v2/person/P1234567890",
"phones": { "displayed": 2, "additional": 0 },
"emails": { "displayed": 1, "additional": 0 },
"historic_addresses": { "displayed": 1, "additional": 0 },
"owned_properties": { "displayed": 0, "additional": 0 }
}
}
]Matched-first for phone
Because the search input was a phone number, the matching phone is pinned to
position 0 of the phones list even when it ranks below other phones by
confidence score. This guarantees the phone the caller queried on always
appears above the cap.
Multiple Results
In rare cases, a phone number may be associated with multiple people. When this occurs, the response includes all matching records sorted by relevance.
Related
Capability Map
Map a user's intent to the exact endpoint and parameters that answer it.
Person Search
Look up individuals by name, phone, or address
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.
Search by Address
Find people by current or historical addresses