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 →