--- title: "Look up what is known about a phone number" method: GET path: "/v2/phone/{phone}" tags: ["Phone V2"] --- # Look up what is known about a phone number `GET /v2/phone/{phone}` ## Request - Base URL: `https://api.whitepages.com` - URL: `https://api.whitepages.com/v2/phone/{phone}` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. A path segment that is not a North American number is rejected before any upstream call. ## Path parameters - `phone` string, required: North American phone number, in any common format. Numbers outside the North American Numbering Plan are not supported. ## Response `200` Phone data retrieved successfully - PhoneLookupV2ResponseDto: What is known about a phone number. - `phone` PhoneFactsDto, required: The number's own facts, present on every successful response. Populated for any well-formed number, including one no party is associated with, which is what makes an empty lookup an answer. - `e164` string, required: The number in E.164 form, the canonical identifier - `national_format` string, required: The number formatted for display, e.g. (206) 555-0198 - `line_type` 'mobile' | 'landline' | 'voip' | 'tollfree' | 'unknown', required: Enumeration of supported phone number types. - `carrier` string, nullable, required: The carrier currently serving the number, or `null` where the provider has none on file - `primary_owner` 'person' | 'business' | 'unknown', required: The kind of party a number most likely belongs to. New members are additive: a caller matching on the members below keeps working when another is introduced. - `returned_people` integer, required: How many person records this response carries - `people_limit` integer, required: The ceiling that applied to the person records - `people_truncated` boolean, required: True when `returned_people` reached `people_limit`, meaning at least that many people are associated with the number and the true figure is unknown. It is true of a result that exactly fills the ceiling as well as one the ceiling cut short: the upstream source reports no count, so the two cannot be told apart - `returned_businesses` integer, required: How many business records this response carries. Upstream returns at most one business per number, so this is `0` or `1` today; it carries no ceiling or truncation counterpart because the business list is never capped - `people` PersonSearchResultDto[], required: People associated with the number, most likely first. `match_score` and `matched_by` are inert here: there is no query for a result to be relevant to - `id` string, nullable, required: Unique identifier for the person - `name` string, required: Full name of the person - `aliases` string[], required: List of aliases for the person - `is_dead` boolean, required: Whether the person is deceased - `owned_properties` OwnedProperty[], required: List of properties owned by the person - `id` string, required - `address` string, required - `phones` PhoneNumber[], required: List of phone numbers, ordered by strength - `number` string, required - `type` 'mobile' | 'landline' | 'voip' | 'tollfree' | 'unknown', required: Enumeration of supported phone number types. - `score` integer, nullable, required: Confidence score 0-100 showing how strongly this phone is linked to the person. Higher scores mean a stronger match. - `date_of_birth` string, nullable, required: Date of birth in ISO format (YYYY-MM-DD) - `linkedin_url` string, nullable, required: LinkedIn profile URL for the person - `company_name` string, nullable, required: Current or most recent company name - `job_title` string, nullable, required: Current or most recent job title - `relatives` Relative[], required: List of relatives associated with the person - `id` string, nullable, required: Unique identifier for the relative - `name` string, required: Full name of the relative - `age` integer, nullable: Calculated age in years derived from date of birth - `current_addresses` AddressDto[], required: List of current residential addresses - `address_id` string, required: Unique address identifier - `full_address` string, required: Complete formatted address string - `city` string, required: City name - `state` string, required: Two-letter state code - `line1` string, required: Street address line (house number and street) - `zip` string, required: 5-digit ZIP code - `historic_addresses` AddressDto[], required: List of historic residential addresses - `address_id` string, required: Unique address identifier - `full_address` string, required: Complete formatted address string - `city` string, required: City name - `state` string, required: Two-letter state code - `line1` string, required: Street address line (house number and street) - `zip` string, required: 5-digit ZIP code - `match_score` integer, nullable: Relevance and completeness score 1-99 - `matched_by` string[]: Which input fields matched this result - `emails` EmailDto[], required: List of email addresses with confidence score - `email` string, required: Email address - `score` integer, required: Confidence score 0-100 for this email association - `result_metadata` ResultMetadataDto, required: Per-result metadata summarizing the displayed-vs-additional counts. Attached only to Person Search results. Person Details continues to return the full lists with no metadata block. - `details_url` string, nullable, required: Canonical Person Details URL for this record, or `null` when the record has no canonical Whitepages person id (e.g., a phone-owner record that did not resolve to a known person) - `phones` ListCountDto, required: Displayed-vs-additional count for one list on a search result. - `displayed` integer, required: Number of items returned in this list on this response - `additional` integer, required: Count of items linked to the person but not included in the response (i.e. upstream_total minus displayed) - `emails` ListCountDto, required: Displayed-vs-additional count for one list on a search result. - `displayed` integer, required: Number of items returned in this list on this response - `additional` integer, required: Count of items linked to the person but not included in the response (i.e. upstream_total minus displayed) - `historic_addresses` ListCountDto, required: Displayed-vs-additional count for one list on a search result. - `displayed` integer, required: Number of items returned in this list on this response - `additional` integer, required: Count of items linked to the person but not included in the response (i.e. upstream_total minus displayed) - `owned_properties` ListCountDto, required: Displayed-vs-additional count for one list on a search result. - `displayed` integer, required: Number of items returned in this list on this response - `additional` integer, required: Count of items linked to the person but not included in the response (i.e. upstream_total minus displayed) - `businesses` BusinessDto[], required: Businesses associated with the number - `name` string, required: Business name - `addresses` BusinessAddressDto[], required: Known street addresses for the business, often empty - `full_address` string, required: Complete formatted address string - `line1` string, required: Street address line (house number and street) - `city` string, required: City name - `state` string, required: Two-letter state code - `zip` string, required: 5-digit ZIP code - `plus4` string, nullable, required: 4-digit ZIP+4 extension, where known - `latlong` LatLong, required: Latitude and longitude coordinates. - `lat` number, required: Latitude coordinate - `lng` number, required: Longitude coordinate - `is_historical` boolean, nullable, required: True where the business is no longer reported at this address, `null` where the source does not say - `approximate_locations` ApproximateLocationDto[], required: Locations known too coarsely to be addresses, so a business placed only within a region still reports where it is - `city` string, nullable, required: City name, where known - `state` string, nullable, required: Two-letter state code, where known - `zip` string, nullable, required: 5-digit ZIP code, where known - `plus4` string, nullable, required: 4-digit ZIP+4 extension, where known - `country` string, nullable, required: Country code as the upstream source spells it, `US` for a domestic location - `latlong` LatLong, required: Latitude and longitude coordinates. - `lat` number, required: Latitude coordinate - `lng` number, required: Longitude coordinate - `is_historical` boolean, required: True where the business is no longer reported at this location. A business reported both now and formerly carries an entry for each, and this is what tells them apart - `precision` 'zip4' | 'zip' | 'city' | 'state' | 'country' | 'unknown', required: The smallest region a location pins down. New members are additive: a caller matching on the members below keeps working when another is introduced. ``UNKNOWN`` absorbs a precision the upstream source introduces before this service knows it, so a new one reaches callers as a location they can still read rather than as a failed request. ## Other responses - `400`: Bad Request - `403`: Forbidden - `422`: Unprocessable Content - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-10-02** `762c5074cb8b`: 1 info - endpoint added [Operation history](https://skmtc.dev/whitepages/apis/whitepages-api-reference/changes/v2/phone/:phone/get.md) --- [API](https://skmtc.dev/whitepages/apis/whitepages-api-reference.md) - [All operations](https://skmtc.dev/whitepages/apis/whitepages-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/whitepages/apis/whitepages-api-reference/revisions/b22cd77a87be?raw)