Skip to content

docs: document the phone lookup endpoint #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lhagenWP merged 1 commit into from
Oct 1, 2026
Merged

docs: document the phone lookup endpoint #66

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
61 changes: 61 additions & 0 deletions content/docs/changelog/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,67 @@ description: Notable changes to the Whitepages Pro API, newest first.

---

## October 1, 2026

### New endpoint: `GET /v2/phone/{phone}`

A phone number now has an endpoint of its own. Person search still accepts
`phone=` and is unchanged; the new endpoint answers a different question —
what is this number — rather than which people rank against it.

```bash title="Request"
curl 'https://api.whitepages.com/v2/phone/12069052100' \
--header 'X-Api-Key: YOUR_API_KEY'
```

```json title="Response"
{
"phone": {
"e164": "+12069052100",
"national_format": "(206) 905-2100",
"line_type": "landline",
"carrier": "Onvoy, LLC",
"primary_owner": "business",
"returned_people": 10,
"people_limit": 10,
"people_truncated": true,
"returned_businesses": 1
},
"people": [{ "...": "..." }],
"businesses": [{ "name": "Space Needle", "...": "..." }]
}
```

**The number's own facts come back even when nobody is associated with it.**
`line_type` and `carrier` are resolved by lookup rather than derived from the
numbering plan, so a number with no owner on file still tells you whether it
is a mobile, a landline, or toll-free. A lookup that finds no parties is a
successful answer, not an error.

**Businesses are returned.** Person search never had anywhere to put them, so
a number belonging to a company came back as the people who had listed it, or
as nothing at all. `businesses` carries the business name, its street address
where one is known, and otherwise the region it is placed within.

**`primary_owner` says which list to read first** — `person`, `business`, or
`unknown`. It classifies the line rather than indexing a list: a switchboard
collects everyone who ever listed it, so a number can report `business` while
`people` is long. Read it as a kind, not as a pointer.

**Several spellings address one number.** `12069052100`, `2069052100`,
`(206) 905-2100`, and `+1-206-905-2100` all resolve to the same resource and
return the same body. The canonical form comes back in the `Content-Location`
header and is itself callable.

The endpoint covers the North American Numbering Plan. A number outside it is
refused with HTTP 400 rather than searched. Each successful lookup bills one
unit, whether or not it found anyone.

See [Reverse Phone Lookup](/documentation/person-search/reverse-phone-lookup)
for when to use this endpoint and when person search is still the better fit.

---

## September 25, 2026

### Property search reports whether it found your address
Expand Down
35 changes: 24 additions & 11 deletions content/docs/documentation/agentic-guidance/capability-map.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,24 +25,37 @@ import { Callout } from "fumadocs-ui/components/callout";
Start here. This table maps what you are trying to do to the endpoint and parameters that do it. Match the intent, copy the parameters, then read the [type document](/references) for that endpoint before writing your types.

<Callout type="warn">
**Person search is one endpoint.** Reverse phone lookup, address lookup, and
name search are all the same `GET /v2/person/` call with different parameters.
There is no separate "phone lookup" endpoint — pass `phone=` to person search.
**Person search is one endpoint.** Address lookup and name search are the same
`GET /v2/person/` call with different parameters. It also accepts `phone=`,
which ranks people against a number.

A phone number has its own endpoint as well. `GET /v2/phone/{phone}` answers
what a number is — line type, carrier, and the people _and businesses_
associated with it — rather than which people rank against it. Pick by the
question you are asking; the row below says which.

</Callout>

## People

| You want to… | Endpoint | Key parameters |
| ---------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------- |
| Reverse phone lookup (who owns a number) | `GET /v2/person/` | `phone=` |
| Find who lives at an address | `GET /v2/person/` | `street`, `city`, `state_code`, `zipcode` |
| Find a person by name | `GET /v2/person/` | `name`, or `first_name` / `middle_name` / `last_name` (+ location) |
| Narrow a person search | `GET /v2/person/` | `min_age` / `max_age`, `include_fuzzy_matching`, `strict_match`, `include_historical_locations`, `radius` |
| Page through person results | `GET /v2/person/` | `page`, `page_size` |
| Get full detail for a known person | `GET /v2/person/{id}` | path `id` (the `id` from any person object) |
| You want to… | Endpoint | Key parameters |
| ---------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
| Find out what a phone number is | `GET /v2/phone/{phone}` | path `phone` (any common spelling) |
| Rank people against a phone number | `GET /v2/person/` | `phone=`, optionally with `name` or location to narrow |
| Find who lives at an address | `GET /v2/person/` | `street`, `city`, `state_code`, `zipcode` |
| Find a person by name | `GET /v2/person/` | `name`, or `first_name` / `middle_name` / `last_name` (+ location) |
| Narrow a person search | `GET /v2/person/` | `min_age` / `max_age`, `include_fuzzy_matching`, `strict_match`, `include_historical_locations`, `radius` |
| Page through person results | `GET /v2/person/` | `page`, `page_size` |
| Get full detail for a known person | `GET /v2/person/{id}` | path `id` (the `id` from any person object) |

A person search returns results scored by `match_score` (1–99). See [Entity Shapes](/documentation/agentic-guidance/entity-shapes) for how a person's shape differs by context.

Choosing between the two phone rows: `GET /v2/phone/{phone}` returns the
number's own facts even when no party is associated with it, and is the only
one that returns businesses. `GET /v2/person/` with `phone=` is the one to use
when you want person records ranked, or when you are combining the number with
a name or a location to verify a match.

## Property

| You want to… | Endpoint | Key parameters |
Expand Down
207 changes: 129 additions & 78 deletions content/docs/documentation/person-search/reverse-phone-lookup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,124 +1,175 @@
---
related:
- /references/phone-v2/get_phone_by_number_v2
- /documentation/agentic-guidance/capability-map
- /documentation/person-search
- /references/person-v2/search_person_by_name_phone_or_address_v2
- /documentation/person-search/search-by-address
title: Reverse Phone Lookup
description: Find the owner of a phone number
description: Find out what a phone number is and who it belongs to
lifecycle: current
topic: person
keywords:
- "reverse phone lookup"
- "phone search"
- "who owns this number"
- "find owner of a phone number"
- "phone line type"
- "phone carrier"
---

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.
import { Callout } from "fumadocs-ui/components/callout";

## Basic Usage
Two endpoints take a phone number, and they answer different questions.

Look up a phone number:
`GET /v2/phone/{phone}` answers **what is this number** — its line type and
carrier, and the people and businesses associated with it. Use it when the
number is the subject of your question.

`GET /v2/person/` with `phone=` answers **which people match this number**,
ranked, and lets you combine the number with a name or a location. Use it when
a person is the subject and the number is one of your criteria.

## Look up a number

```bash title="Request"
curl 'https://api.whitepages.com/v2/person?phone=2065550198' \
curl 'https://api.whitepages.com/v2/phone/12069052100' \
--header 'X-Api-Key: YOUR_API_KEY'
```

This returns person records associated with the phone number.
```json title="Response"
{
"phone": {
"e164": "+12069052100",
"national_format": "(206) 905-2100",
"line_type": "landline",
"carrier": "Onvoy, LLC",
"primary_owner": "business",
"returned_people": 10,
"people_limit": 10,
"people_truncated": true,
"returned_businesses": 1
},
"people": [{ "...": "..." }],
"businesses": [
{
"name": "Space Needle",
"addresses": [],
"approximate_locations": [
{
"city": "Seattle",
"state": "WA",
"zip": "98040",
"plus4": null,
"country": null,
"latlong": { "lat": 47.6079, "lng": -122.3317 },
"is_historical": false,
"precision": "zip"
}
]
}
]
}
```

## Parameters
### Spellings

| Parameter | Type | Description |
| --------- | ------ | ----------------------- |
| `phone` | string | Phone number to look up |
Any common spelling addresses the same number. These four are one resource and
return one body:

## Examples
```
/v2/phone/12069052100
/v2/phone/2069052100
/v2/phone/(206)%20905-2100
/v2/phone/%2B1-206-905-2100
```

### Basic Phone Lookup
The canonical form comes back in the `Content-Location` response header and is
itself callable, so a client that normalises on its own side can follow it
instead of writing its own rules.

Find who owns a phone number:
The endpoint covers the North American Numbering Plan. A number outside it is
refused with HTTP 400 rather than searched.

```bash
curl 'https://api.whitepages.com/v2/person?phone=2125550198' \
--header 'X-Api-Key: YOUR_API_KEY'
```
## Reading the response

### Combine with Name for Verification
### `phone` — the number's own facts

Verify that a phone number belongs to a specific person:
Present on every successful response, including one where nothing is
associated with the number. `line_type` and `carrier` are resolved by lookup
rather than derived from the numbering plan, so an unlisted number still tells
you whether it is a mobile, a landline, or toll-free. Toll-free numbers resolve
without a carrier and carry `null`.

```bash
curl 'https://api.whitepages.com/v2/person?phone=2125550198&name=John%20Smith' \
--header 'X-Api-Key: YOUR_API_KEY'
```
A lookup that finds no parties is an answer, not an error — you still learn
what kind of line it is.

### `primary_owner` — which list to read first

`person`, `business`, or `unknown`.

<Callout type="info" title="A kind, not a pointer">
`primary_owner` classifies the line, and `business` can appear alongside a
long `people` list or an empty `businesses` list. A switchboard collects
everyone who ever listed it, so people count is a poor signal of ownership.
Read it as a kind and use both lists.
</Callout>

### Combine with Location
### `businesses`

Narrow results by adding location filters:
A business carries its name and, where one is known, its street address. Where
no street address is known it carries `approximate_locations` instead: the
postal code or city the business is placed within, with `precision` naming how
closely. The two lists do not overlap — a location is an address or it is
approximate.

### `people`

Person records in the same shape person search returns. `match_score` and
`matched_by` appear on every record and are inert here: there is no query for a
result to be relevant to.

`returned_people` is how many this response carries, `people_limit` is the
ceiling that applied, and `people_truncated` says the ceiling was reached.
Truncated with ten returned means at least ten are associated and the true
figure is unknown.

## Ranking people against a number

When you want person records ranked, or want to combine the number with other
criteria, use person search.

Verify that a number belongs to a particular person:

```bash
curl 'https://api.whitepages.com/v2/person?phone=2125550198&state_code=NY' \
curl 'https://api.whitepages.com/v2/person/?phone=2125550198&name=John%20Smith' \
--header 'X-Api-Key: YOUR_API_KEY'
```

<Callout type="tip" title="Use Cases">
Reverse phone lookup is useful for verifying caller identity, confirming
contact information accuracy, and enriching customer records with additional
details.
</Callout>

## Response
Narrow by location:

The response includes the phone owner's information along with all associated contact details:

```json title="Response"
[
{
"id": "P1234567890",
"name": "John Smith",
"aliases": ["Johnny 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": 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 }
}
}
]
```bash
curl 'https://api.whitepages.com/v2/person/?phone=2125550198&state_code=NY' \
--header 'X-Api-Key: YOUR_API_KEY'
```

<Callout type="info" title="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.
position 0 of each record's `phones` list even when it ranks below other
phones by confidence score. The phone you queried on always appears above the
cap.
</Callout>

<Callout type="info" title="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.
</Callout>
## Choosing between them

| If you want to… | Use |
| ------------------------------------------------------------ | ----------------------- |
| Know the line type or carrier | `GET /v2/phone/{phone}` |
| Find the business behind a number | `GET /v2/phone/{phone}` |
| Get an answer even when nobody is associated with the number | `GET /v2/phone/{phone}` |
| Rank people against the number | `GET /v2/person/` |
| Confirm a number belongs to a named person | `GET /v2/person/` |
| Combine the number with an address or age filter | `GET /v2/person/` |

Each successful lookup bills one unit on either endpoint, whether or not it
found anyone.
10 changes: 10 additions & 0 deletions content/docs/references/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,16 @@ Account management endpoints for retrieving usage statistics.
/>
</Cards>

## Phone V2 API

<Cards>
<Card
title="Look up what is known about a phone number"
description="Retrieve the number's own facts and the parties associated with it."
href="/references/phone-v2/get_phone_by_number_v2"
/>
</Cards>

## Property V2 API

<Cards>
Expand Down
1 change: 1 addition & 0 deletions content/docs/references/person-v2/search_person_by_name_phone_or_address_v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ related:
- /documentation/person-search
- /documentation/agentic-guidance/capability-map
- /references/person-v2/get_person_by_id_v2
- /references/phone-v2/get_phone_by_number_v2
- /references/authentication
- /references/rate-limits
lifecycle: current
Expand Down
Loading
Loading