diff --git a/content/docs/changelog/index.mdx b/content/docs/changelog/index.mdx
index 1d16efe..c4d8283 100644
--- a/content/docs/changelog/index.mdx
+++ b/content/docs/changelog/index.mdx
@@ -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": []
}
```
@@ -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.
diff --git a/content/docs/documentation/getting-started.mdx b/content/docs/documentation/getting-started.mdx
index b0f017b..dd79ca0 100644
--- a/content/docs/documentation/getting-started.mdx
+++ b/content/docs/documentation/getting-started.mdx
@@ -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"
/>
+
+ Every value on this page is fictitious. Phone numbers come from the `555-01xx`
+ range reserved for documentation, and the identifiers are placeholders.
+
+
+### 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"
}
@@ -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
diff --git a/content/docs/references/events/search_events.mdx b/content/docs/references/events/search_events.mdx
index 98a924c..23995e7 100644
--- a/content/docs/references/events/search_events.mdx
+++ b/content/docs/references/events/search_events.mdx
@@ -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
@@ -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. */}
diff --git a/content/docs/references/meta.json b/content/docs/references/meta.json
index 4b672ec..e0a4295 100644
--- a/content/docs/references/meta.json
+++ b/content/docs/references/meta.json
@@ -12,6 +12,7 @@
"versioning",
"migration",
"person-v2",
+ "phone-v2",
"webhooks",
"events",
"property-v2",
diff --git a/content/docs/references/person-v2/search_person_by_name_phone_or_address_v2.mdx b/content/docs/references/person-v2/search_person_by_name_phone_or_address_v2.mdx
index 66b32b4..bdaa7c8 100644
--- a/content/docs/references/person-v2/search_person_by_name_phone_or_address_v2.mdx
+++ b/content/docs/references/person-v2/search_person_by_name_phone_or_address_v2.mdx
@@ -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
@@ -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. */}
diff --git a/content/docs/references/phone-v2/get_phone_by_number_v2.mdx b/content/docs/references/phone-v2/get_phone_by_number_v2.mdx
index c470b5b..2d6050f 100644
--- a/content/docs/references/phone-v2/get_phone_by_number_v2.mdx
+++ b/content/docs/references/phone-v2/get_phone_by_number_v2.mdx
@@ -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
@@ -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. */}
diff --git a/content/docs/references/property-v2/get_property_by_id_v2.mdx b/content/docs/references/property-v2/get_property_by_id_v2.mdx
index 2159350..ddda82b 100644
--- a/content/docs/references/property-v2/get_property_by_id_v2.mdx
+++ b/content/docs/references/property-v2/get_property_by_id_v2.mdx
@@ -13,8 +13,8 @@ title: Get property details by ID
description: |-
Retrieve detailed property information by Whitepages property ID.
- Accepts either a Whitepages property ID (prefix ``R``) or an address ID
- (prefix ``A``). Address IDs are resolved to the associated property
+ Accepts either a Whitepages property ID (prefix `R`) or an address ID
+ (prefix `A`). Address IDs are resolved to the associated property
before lookup.
This endpoint returns comprehensive property data including physical
@@ -35,10 +35,9 @@ _openapi:
Retrieve detailed property information by Whitepages property ID.
- Accepts either a Whitepages property ID (prefix ``R``) or an address
- ID
+ Accepts either a Whitepages property ID (prefix `R`) or an address ID
- (prefix ``A``). Address IDs are resolved to the associated property
+ (prefix `A`). Address IDs are resolved to the associated property
before lookup.
diff --git a/content/docs/references/property-v2/search_property_v2.mdx b/content/docs/references/property-v2/search_property_v2.mdx
index 3885d7f..a786c8c 100644
--- a/content/docs/references/property-v2/search_property_v2.mdx
+++ b/content/docs/references/property-v2/search_property_v2.mdx
@@ -25,13 +25,9 @@ description: |-
Search ranks by text relevance, so the closest match to an address
that does not exist may be a different property on the same street.
- Pass ``strict_match=true`` to receive only the address supplied or
- an address in the same building.
-
- Raises
- ------
- StrictMatchRequiresStreetError
- If ``strict_match`` was requested without a street.
+ Pass `strict_match=true` to receive only the address supplied or
+ an address in the same building; it needs a street to match against,
+ so a request setting it without one is rejected.
full: true
_openapi:
method: GET
@@ -61,17 +57,11 @@ _openapi:
that does not exist may be a different property on the same street.
- Pass ``strict_match=true`` to receive only the address supplied or
-
- an address in the same building.
-
-
- Raises
+ Pass `strict_match=true` to receive only the address supplied or
- ------
+ an address in the same building; it needs a street to match against,
- StrictMatchRequiresStreetError
- If ``strict_match`` was requested without a street.
+ so a request setting it without one 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. */}