From bc74b26118f21f3ff8f5a9886341539d15e9cddd Mon Sep 17 00:00:00 2001 From: Leif Hagen Date: Fri, 2 Oct 2026 13:23:33 -0400 Subject: [PATCH 1/2] docs: use fictitious data and make the phone reference reachable The phone lookup examples were a live response captured from a running service: a real business, its real carrier, its real number. Replace them with fictitious values on the pattern the other guides already use, from the 555-01xx range reserved for documentation, and say so in the guide. The business example stays, since approximate_locations needs one to illustrate, but the business is invented too. The reference page had no way in. The References rail lists its directories by hand and phone-v2 was missing from that list, so the page was reachable only by typing its URL. Getting Started mentioned a phone number only as something person search accepts. --- content/docs/changelog/index.mdx | 26 +-- .../docs/documentation/getting-started.mdx | 7 +- .../person-search/reverse-phone-lookup.mdx | 151 ++++++++++++++++-- content/docs/references/meta.json | 1 + 4 files changed, 159 insertions(+), 26 deletions(-) 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/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", From b5ace223e06ea3186eea50574783ca98bccf21b2 Mon Sep 17 00:00:00 2001 From: Leif Hagen Date: Fri, 2 Oct 2026 13:23:33 -0400 Subject: [PATCH 2/2] docs: regenerate reference pages from the cleaned spec The service stopped publishing its handler docstrings, so the spec these pages are generated from no longer carries numpydoc sections or the reStructuredText markup the site renders as literal backticks. Descriptions only. Five pages: the phone lookup loses a Parameters and Returns block naming Python arguments and internal types, person, property and deed-event search lose Raises blocks naming exception classes, and the property detail page's code spans render as code. --- .../docs/references/events/search_events.mdx | 12 ++---- ...rch_person_by_name_phone_or_address_v2.mdx | 16 +++---- .../phone-v2/get_phone_by_number_v2.mdx | 42 +++---------------- .../property-v2/get_property_by_id_v2.mdx | 9 ++-- .../property-v2/search_property_v2.mdx | 22 +++------- 5 files changed, 26 insertions(+), 75 deletions(-) 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/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. */}