From ec66e5c0f3b95cab95cb371f0c8f99f1ec330531 Mon Sep 17 00:00:00 2001 From: Leif Hagen Date: Thu, 1 Oct 2026 15:47:18 -0400 Subject: [PATCH] docs: document the phone lookup endpoint A phone number has its own endpoint now, and the docs said the opposite. The capability map told readers in a warning callout that no separate phone lookup endpoint exists and to pass phone= to person search, which becomes wrong the moment this ships. Rewrite the reverse phone lookup guide around the two endpoints and when each is the right one: /v2/phone/{phone} when the number is the subject, person search when a person is and the number is one of the criteria. The guide's example response was already wrong before this change, showing a bare array where v2 person returns an object, so it is replaced with a real response rather than patched. Correct the capability map's callout and split its one phone row into two, since the rows now answer different questions. Generate the reference page from the published spec and give it facets: the phone directory takes the person topic, since a lookup returns people and businesses rather than warranting a facet of its own, and person search now lists the phone reference among its related pages. Add a changelog entry covering the endpoint, the facts it returns for a number nobody is associated with, businesses reaching a response for the first time, and how primary_owner should be read, and point the changelog banner at it. --- content/docs/changelog/index.mdx | 61 ++++++ .../agentic-guidance/capability-map.mdx | 35 ++- .../person-search/reverse-phone-lookup.mdx | 207 +++++++++++------- content/docs/references/index.mdx | 10 + ...rch_person_by_name_phone_or_address_v2.mdx | 1 + .../phone-v2/get_phone_by_number_v2.mdx | 76 +++++++ content/docs/references/phone-v2/meta.json | 4 + scripts/generators/openapi/openapi.facets.ts | 19 ++ src/components/layout/changelog-banner.tsx | 4 +- 9 files changed, 326 insertions(+), 91 deletions(-) create mode 100644 content/docs/references/phone-v2/get_phone_by_number_v2.mdx create mode 100644 content/docs/references/phone-v2/meta.json diff --git a/content/docs/changelog/index.mdx b/content/docs/changelog/index.mdx index 9f6470d..1d16efe 100644 --- a/content/docs/changelog/index.mdx +++ b/content/docs/changelog/index.mdx @@ -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 diff --git a/content/docs/documentation/agentic-guidance/capability-map.mdx b/content/docs/documentation/agentic-guidance/capability-map.mdx index b89d020..5dcd5c4 100644 --- a/content/docs/documentation/agentic-guidance/capability-map.mdx +++ b/content/docs/documentation/agentic-guidance/capability-map.mdx @@ -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. - **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. + ## 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 | diff --git a/content/docs/documentation/person-search/reverse-phone-lookup.mdx b/content/docs/documentation/person-search/reverse-phone-lookup.mdx index cc675d4..f0dca4e 100644 --- a/content/docs/documentation/person-search/reverse-phone-lookup.mdx +++ b/content/docs/documentation/person-search/reverse-phone-lookup.mdx @@ -1,11 +1,12 @@ --- 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: @@ -13,112 +14,162 @@ keywords: - "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`. + + + `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. + -### 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' ``` - - Reverse phone lookup is useful for verifying caller identity, confirming - contact information accuracy, and enriching customer records with additional - details. - - -## 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' ``` 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. - - In rare cases, a phone number may be associated with multiple people. When - this occurs, the response includes all matching records sorted by relevance. - +## 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. diff --git a/content/docs/references/index.mdx b/content/docs/references/index.mdx index 0c06877..a5aec35 100644 --- a/content/docs/references/index.mdx +++ b/content/docs/references/index.mdx @@ -52,6 +52,16 @@ Account management endpoints for retrieving usage statistics. /> +## Phone V2 API + + + + + ## Property V2 API 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 c808b57..66b32b4 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 @@ -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 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 new file mode 100644 index 0000000..c470b5b --- /dev/null +++ b/content/docs/references/phone-v2/get_phone_by_number_v2.mdx @@ -0,0 +1,76 @@ +--- +related: + - /documentation/person-search/reverse-phone-lookup + - /documentation/agentic-guidance/capability-map + - /references/person-v2/search_person_by_name_phone_or_address_v2 + - /references/authentication + - /references/rate-limits +lifecycle: current +topic: person +keywords: + - "reverse phone lookup" + - "phone lookup" + - "who owns this number" + - "phone line type" + - "phone carrier" + - "business behind a phone number" +title: Look up what is known about a phone number +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. +full: true +_openapi: + method: GET + toc: [] + structuredData: + headings: [] + contents: + - content: |- + 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. +--- + +{/* 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/meta.json b/content/docs/references/phone-v2/meta.json new file mode 100644 index 0000000..e89944f --- /dev/null +++ b/content/docs/references/phone-v2/meta.json @@ -0,0 +1,4 @@ +{ + "title": "Phone V2", + "pages": ["get_phone_by_number_v2"] +} diff --git a/scripts/generators/openapi/openapi.facets.ts b/scripts/generators/openapi/openapi.facets.ts index 621220a..3250efd 100644 --- a/scripts/generators/openapi/openapi.facets.ts +++ b/scripts/generators/openapi/openapi.facets.ts @@ -9,6 +9,9 @@ export interface Facets { const DIRECTORY_TOPICS: Record = { "person-v2": "person", + // A phone lookup returns people and businesses, so it belongs to the + // person topic rather than a facet value of its own. + "phone-v2": "person", "property-v2": "property", events: "deed-events", webhooks: "webhooks", @@ -16,6 +19,14 @@ const DIRECTORY_TOPICS: Record = { }; const FILE_KEYWORDS: Record = { + "phone-v2/get_phone_by_number_v2.mdx": [ + "reverse phone lookup", + "phone lookup", + "who owns this number", + "phone line type", + "phone carrier", + "business behind a phone number", + ], "person-v2/search_person_by_name_phone_or_address_v2.mdx": [ "reverse phone lookup", "phone search", @@ -76,10 +87,18 @@ const FILE_KEYWORDS: Record = { }; const FILE_RELATED: Record = { + "phone-v2/get_phone_by_number_v2.mdx": [ + "/documentation/person-search/reverse-phone-lookup", + "/documentation/agentic-guidance/capability-map", + "/references/person-v2/search_person_by_name_phone_or_address_v2", + "/references/authentication", + "/references/rate-limits", + ], "person-v2/search_person_by_name_phone_or_address_v2.mdx": [ "/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", ], diff --git a/src/components/layout/changelog-banner.tsx b/src/components/layout/changelog-banner.tsx index da86922..a3a5245 100644 --- a/src/components/layout/changelog-banner.tsx +++ b/src/components/layout/changelog-banner.tsx @@ -13,12 +13,12 @@ export function ChangelogBanner() { return ( - New: match confidence on property search, strict matching, and more.{" "} + New: look up a phone number on its own endpoint, businesses included.{" "} See what's changed →