Skip to content

docs: use fictitious data and make the phone reference reachable #67

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
trichardswp merged 2 commits into from
Oct 2, 2026
Merged

docs: use fictitious data and make the phone reference reachable #67

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bc74b26
docs: use fictitious data and make the phone reference reachable
lhagenWP Oct 2, 2026
b5ace22
docs: regenerate reference pages from the cleaned spec
lhagenWP Oct 2, 2026
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
26 changes: 13 additions & 13 deletions content/docs/changelog/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,25 +18,25 @@ A phone number now has an endpoint of its own. Person search still accepts
what is this number — rather than which people rank against it.

```bash title="Request"
curl 'https://api.whitepages.com/v2/phone/12069052100' \
curl 'https://api.whitepages.com/v2/phone/12065550142' \
--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,
"e164": "+12065550142",
"national_format": "(206) 555-0142",
"line_type": "mobile",
"carrier": "Example Wireless",
"primary_owner": "person",
"returned_people": 1,
"people_limit": 10,
"people_truncated": true,
"returned_businesses": 1
"people_truncated": false,
"returned_businesses": 0
},
"people": [{ "...": "..." }],
"businesses": [{ "name": "Space Needle", "...": "..." }]
"people": [{ "name": "John Smith", "...": "..." }],
"businesses": []
}
```

Expand All @@ -56,8 +56,8 @@ where one is known, and otherwise the region it is placed within.
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
**Several spellings address one number.** `12065550142`, `2065550142`,
`(206) 555-0142`, and `+1-206-555-0142` 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.

Expand Down
7 changes: 6 additions & 1 deletion content/docs/documentation/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,11 @@ To access the API, you'll need an API key. Sign up for a **free trial** at [whit
href="/documentation/person-search"
description="Look up individuals by name, phone, or address"
/>
<Card
title="Phone Lookup"
href="/documentation/person-search/reverse-phone-lookup"
description="Find out what a phone number is and who it belongs to"
/>
<Card
title="Property Search"
href="/documentation/property-search"
Expand All @@ -56,4 +61,4 @@ Responses are returned in JSON format. Each successful request consumes one bill

## Next Steps

Ready to make your first API call? Start with the [Person Search](/documentation/person-search) tutorial.
Ready to make your first API call? Start with the [Person Search](/documentation/person-search) tutorial, or [Phone Lookup](/documentation/person-search/reverse-phone-lookup) if you are starting from a phone number.
151 changes: 139 additions & 12 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
Expand Up @@ -33,36 +33,158 @@ 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/phone/12069052100' \
curl 'https://api.whitepages.com/v2/phone/12065550142' \
--header 'X-Api-Key: YOUR_API_KEY'
```

```json title="Response"
{
"phone": {
"e164": "+12069052100",
"national_format": "(206) 905-2100",
"e164": "+12065550142",
"national_format": "(206) 555-0142",
"line_type": "mobile",
"carrier": "Example Wireless",
"primary_owner": "person",
"returned_people": 1,
"people_limit": 10,
"people_truncated": false,
"returned_businesses": 0
},
"people": [
{
"id": "P1234567890",
"name": "John Smith",
"aliases": ["Jonathan Smith", "Jon Smith"],
"is_dead": false,
"age": 40,
"date_of_birth": "1985-03-00",
"linkedin_url": "https://www.linkedin.com/in/example-john-smith",
"company_name": "Acme Corp",
"job_title": "Software Engineer",
"match_score": null,
"matched_by": ["phone"],
"phones": [
{ "number": "(206) 555-0142", "type": "mobile", "score": 95 },
{ "number": "(206) 555-0177", "type": "landline", "score": 72 }
],
"current_addresses": [
{
"address_id": "A9876543210",
"full_address": "123 Main St Seattle, WA 98101",
"line1": "123 Main St",
"city": "Seattle",
"state": "WA",
"zip": "98101"
}
],
"historic_addresses": [
{
"address_id": "A1234567890",
"full_address": "456 Oak Ave Portland, OR 97204",
"line1": "456 Oak Ave",
"city": "Portland",
"state": "OR",
"zip": "97204"
}
],
"owned_properties": [
{ "id": "R1234567890", "address": "123 Main St Seattle, WA 98101" }
],
"emails": [
{ "email": "john.smith@example.com", "score": 92 },
{ "email": "jsmith@example.net", "score": 68 }
],
"relatives": [{ "id": "P0987654321", "name": "Jane Smith" }],
"result_metadata": {
"details_url": "/v2/person/P1234567890",
"phones": { "displayed": 2, "additional": 1 },
"emails": { "displayed": 2, "additional": 0 },
"historic_addresses": { "displayed": 1, "additional": 3 },
"owned_properties": { "displayed": 1, "additional": 0 }
}
}
],
"businesses": []
}
```

<Callout type="info" title="Example data">
Every value on this page is fictitious. Phone numbers come from the `555-01xx`
range reserved for documentation, and the identifiers are placeholders.
</Callout>

### A switchboard

A company line collects everyone who has ever listed it, so `people` can be
long while the number belongs to the business. This is the case
`primary_owner` exists for: it reports `business` even though ten person
records came back.

```json title="Response"
{
"phone": {
"e164": "+12065550188",
"national_format": "(206) 555-0188",
"line_type": "landline",
"carrier": "Onvoy, LLC",
"carrier": "Example Telecom",
"primary_owner": "business",
"returned_people": 10,
"people_limit": 10,
"people_truncated": true,
"returned_businesses": 1
},
"people": [{ "...": "..." }],
"people": [
{
"id": "P2345678901",
"name": "Maria Chen",
"aliases": [],
"is_dead": false,
"age": 34,
"date_of_birth": "1992-07-00",
"linkedin_url": null,
"company_name": "Acme Plumbing",
"job_title": "Dispatcher",
"match_score": null,
"matched_by": ["phone"],
"phones": [
{ "number": "(206) 555-0188", "type": "landline", "score": 61 },
{ "number": "(206) 555-0131", "type": "mobile", "score": 88 }
],
"current_addresses": [
{
"address_id": "A2345678901",
"full_address": "77 Cedar Ln Seattle, WA 98101",
"line1": "77 Cedar Ln",
"city": "Seattle",
"state": "WA",
"zip": "98101"
}
],
"historic_addresses": [],
"owned_properties": [],
"emails": [{ "email": "m.chen@example.com", "score": 74 }],
"relatives": [],
"result_metadata": {
"details_url": "/v2/person/P2345678901",
"phones": { "displayed": 2, "additional": 0 },
"emails": { "displayed": 1, "additional": 0 },
"historic_addresses": { "displayed": 0, "additional": 0 },
"owned_properties": { "displayed": 0, "additional": 0 }
}
}
],
"businesses": [
{
"name": "Space Needle",
"name": "Acme Plumbing",
"addresses": [],
"approximate_locations": [
{
"city": "Seattle",
"state": "WA",
"zip": "98040",
"zip": "98101",
"plus4": null,
"country": null,
"latlong": { "lat": 47.6079, "lng": -122.3317 },
"latlong": { "lat": 47.6062, "lng": -122.3321 },
"is_historical": false,
"precision": "zip"
}
Expand All @@ -72,16 +194,21 @@ curl 'https://api.whitepages.com/v2/phone/12069052100' \
}
```

`people` is shown with one record for length; the response carries ten, and
`people_truncated` says the ceiling was reached. Note the phone the query
matched is pinned first in each record's `phones` even where another scores
higher — `(206) 555-0188` scores 61 against the mobile's 88.

### Spellings

Any common spelling addresses the same number. These four are one resource and
return one body:

```
/v2/phone/12069052100
/v2/phone/2069052100
/v2/phone/(206)%20905-2100
/v2/phone/%2B1-206-905-2100
/v2/phone/12065550142
/v2/phone/2065550142
/v2/phone/(206)%20555-0142
/v2/phone/%2B1-206-555-0142
```

The canonical form comes back in the `Content-Location` response header and is
Expand Down
12 changes: 4 additions & 8 deletions content/docs/references/events/search_events.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,8 @@ title: Search all deed events
description: |-
Search historical deed events by region and optional filters.

Raises
------
EventInvalidParameterError
When event_date_from is after event_date_to.
A request whose `event_date_from` falls after its `event_date_to`
is rejected.
full: true
_openapi:
method: GET
Expand All @@ -26,10 +24,8 @@ _openapi:
- content: |-
Search historical deed events by region and optional filters.

Raises
------
EventInvalidParameterError
When event_date_from is after event_date_to.
A request whose `event_date_from` falls after its `event_date_to`
is rejected.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Expand Down
1 change: 1 addition & 0 deletions content/docs/references/meta.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@
"versioning",
"migration",
"person-v2",
"phone-v2",
"webhooks",
"events",
"property-v2",
Expand Down
16 changes: 6 additions & 10 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 @@ -20,11 +20,9 @@ title: Search for a person by name, phone number, and address
description: |-
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.
`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.
full: true
_openapi:
method: GET
Expand All @@ -35,11 +33,9 @@ _openapi:
- content: |-
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.
`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.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Expand Down
42 changes: 6 additions & 36 deletions content/docs/references/phone-v2/get_phone_by_number_v2.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,24 +19,9 @@ description: |-
Retrieve the number's own facts and the parties associated with it.

Several spellings of one number address this resource, so the
canonical form goes out in ``Content-Location`` for a caller
normalizing on their side.

Parameters
----------
response : Response
Carries the canonical form back to the caller.
phone : str
North American phone number in any common format.
_query_params : EmptyQueryParams
Present to reject query parameters; the lookup takes none.

Returns
-------
PhoneLookupV2ResponseDto
The number's facts and the parties associated with it. A path
segment that is not a North American number is rejected before
any upstream call.
canonical form goes out in `Content-Location` for a caller
normalizing on their side. A path segment that is not a North
American number is rejected before any upstream call.
full: true
_openapi:
method: GET
Expand All @@ -48,24 +33,9 @@ _openapi:
Retrieve the number's own facts and the parties associated with it.

Several spellings of one number address this resource, so the
canonical form goes out in ``Content-Location`` for a caller
normalizing on their side.

Parameters
----------
response : Response
Carries the canonical form back to the caller.
phone : str
North American phone number in any common format.
_query_params : EmptyQueryParams
Present to reject query parameters; the lookup takes none.

Returns
-------
PhoneLookupV2ResponseDto
The number's facts and the parties associated with it. A path
segment that is not a North American number is rejected before
any upstream call.
canonical form goes out in `Content-Location` for a caller
normalizing on their side. A path segment that is not a North
American number is rejected before any upstream call.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
Expand Down
Loading
Loading