Changelog

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.

Request

curl 'https://api.whitepages.com/v2/phone/12065550142' \
  --header 'X-Api-Key: YOUR_API_KEY'

Response

{
  "phone": {
    "e164": "+12065550142",
    "national_format": "(206) 555-0142",
    "line_type": "mobile",
    "carrier": "Example Wireless",
    "primary_owner": "person",
    "returned_people": 1,
    "people_limit": 10,
    "people_truncated": false,
    "returned_businesses": 0
  },
  "people": [{ "name": "John Smith", "...": "..." }],
  "businesses": []
}

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. 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.

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 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

GET /v2/property/ ranks properties by how closely they match the address text you send, so the closest match to an address that does not exist could be a different property on the same street — and nothing in the response said so. Every response now carries a property_metadata block naming what you got:

"property_metadata": {
  "confidence_score": 100,
  "match_type": "exact",
  "details_url": "/v2/property/RSAMPLE0001"
}

match_type is exact when the property is the address you searched for and best match when it is the closest thing found. confidence_score grades that 0–100: 100 for the address itself, 90 for a different unit in the same building, 50 for the closest match at a different address, and 25 when the address you searched for is not deliverable. Both are null when the address could not be checked, which happens when the request carries no street, or a street with neither a city nor a zipcode to place it. The property is still returned. See Property Search.

New strict_match request parameter. Set strict_match=true to receive only the address you searched for or an address in the same building; anything else returns 404, as does a result the API cannot verify. The parameter needs a street to compare against, so a request without one returns 400.

Owner and resident records gain scores, age, and employment

Owners and residents on GET /v2/property/ and GET /v2/property/{property_id} now carry age, company_name and job_title, and their phones and emails each carry a confidence score (0–100), matching the person endpoints. See Confidence Scores.

Contact lists are now capped. Each person returns at most 4 phone numbers and 3 email addresses, highest score first, with a person_owner_metadata block on owners and a resident_metadata block on residents reporting what was held back:

"person_owner_metadata": {
  "details_url": "/v2/person/PSAMPLE0001",
  "phones": { "displayed": 4, "additional": 3 },
  "emails": { "displayed": 3, "additional": 1 },
  "owned_properties": { "displayed": 1, "additional": 3 }
}

displayed is the count of items in the list on this response; additional is the count of items linked to the person that were not included because the list is capped. The full lists are always available via details_url at /v2/person/{id}. If you relied on property search returning every phone and email for a person, read them from there instead.

Phone shape on property records now matches the person endpoints

Phone type and number on property owners and residents did not match the same fields on GET /v2/person/, so one phone number looked different depending on which endpoint returned it. Both endpoints now use one vocabulary and one format:

// before
{ "number": "12065550142", "type": "Mobile" }
// now
{ "number": "(206) 555-0142", "type": "mobile" }

type is lower case (mobile, landline, voip, tollfree, unknown) and number is nationally formatted. If you match phone values across the property and person endpoints, they now compare directly; if you parse either field from property responses, update that parsing.

New property fields

GET /v2/property/ now returns address_id, property_purpose, owner_occupied, is_vacant and ownership_info.sale_date. owner_occupied is one of OwnerOccupied, AbsenteeOwner or Unknown, or null when occupancy is not on file.

August 4, 2026

Fewer empty responses on person search

Three changes to how GET /v2/person/ and GET /v1/person/ narrow results substantially reduce the number of searches that return no results. None of them break the response shape or require callers to update existing integrations.

Automatic fuzzy-match fallback on zero results. When an exact-name search returns no results, the API now automatically retries the same request with fuzzy matching enabled (phonetic variants, nicknames, initials, typos) before returning. Exact-first precision is preserved for searches that succeed on the first pass; only zero-result searches trigger the fallback. The include_fuzzy_matching request parameter continues to work as documented — setting it to true still forces fuzzy matching on the first pass. Setting it to false (the default) no longer disables fuzzy matching outright; it disables it only for the first pass. See Fuzzy Matching for details.

New strict_match request parameter to opt out of the fallback. Callers whose use case treats "no results" as authoritative (for example, verifying a name genuinely does not exist in the dataset) can now set strict_match=true on the request to suppress the automatic fuzzy fallback. A zero-result exact query is returned as-is, without retrying. strict_match=true and include_fuzzy_matching=true are semantically contradictory; setting both on the same request returns HTTP 400.

Age filter no longer excludes records without a known DOB. When min_age or max_age is set, records for which no date of birth is on file are now included in results. The filter continues to exclude records whose known DOB falls outside the requested range — the behaviour change only affects records with a null age field. A strong name-and-address match now returns even when the person's age is unknown, where previously any age filter would drop that record. See Filter by Age Range.

August 3, 2026

`age` field on v2 person responses

Every record returned by GET /v2/person/ and GET /v2/person/{id} now includes an age field alongside date_of_birth:

{
  "id": "P19Xrg1Zr34",
  "name": "Jane Smith",
  "is_dead": false,
  "age": 68,
  "date_of_birth": "1957-12-00",
  "...": "..."
}

age is computed from date_of_birth at response time. When only a birth year is on file, age is a year-based approximation. When the DOB is missing or unparseable, age is null. Existing min_age / max_age request parameters filter by the same computed age; there is no behavior change to those parameters.

This change is purely additive: no existing field on Person Search or Person Details has changed type, nullability, or presence.

Response key order was also normalized on both endpoints so identity fields and match signals appear before the larger array fields; rely on key names, not position, when parsing.

June 18, 2026

`result_metadata` on v2 person search

Every record in a GET /v2/person/ response now carries a top-level result_metadata object summarizing each list and linking back to the canonical Person Details URL:

{
  "results": [
    {
      "id": "P19Xrg1Zr34",
      "name": "...",
      "phones": [...],
      "emails": [...],
      "historic_addresses": [...],
      "owned_properties": [...],
      "result_metadata": {
        "details_url": "/v2/person/P19Xrg1Zr34",
        "phones":             { "displayed": 3, "additional": 0 },
        "emails":             { "displayed": 1, "additional": 0 },
        "historic_addresses": { "displayed": 4, "additional": 0 },
        "owned_properties":   { "displayed": 0, "additional": 0 }
      }
    }
  ],
  "metadata": { ... }
}

displayed is the actual length of the list on this response; additional is the count linked to the person but not included. Today additional is always 0. A future release will tune Person Search to behave more like search: lean, ranked previews of each list focused on the items most likely to help a caller pick a match and decide whether to traverse for the full record. Payloads will be smaller and results easier to scan. Person Details (details_url) will always carry the full lists for callers who want everything; additional is the forward-compatible signal for how many more items live there. Safe to begin parsing now.

details_url is null for the rare result that arrives without a canonical Whitepages person ID (e.g., an unresolved phone-owner record); those records aren't part of the upcoming tuning.

This change is purely additive: no existing field on Person Search responses has changed type, nullability, or presence.

June 1, 2026

Address ID support on property details

GET /v2/property/{property_id} now accepts either a Whitepages property ID (R prefix) or an address ID (A prefix). Address IDs are resolved to the associated property before lookup, so you can look up property details directly from the address IDs found throughout other API responses.

Not every address ID has full property details, so lookups by address ID may return 404. These responses are not billed.

Billability changes

Billing rules have been simplified:

400 Bad Request responses are no longer billable on any endpoint.
404 Not Found responses on GET /v2/property/{property_id} are no longer billable, so you can optimistically look up property details by address ID.

2xx responses remain billable, as do 404 responses on all other endpoints. See Billing for the full policy. These changes apply to usage from June 1, 2026 onward — usage on or before May 31, 2026 is governed by the prior billing policy.

April 22, 2026

Pagination on v2 person search

The v2 person search endpoint now supports pagination. Use page (1–10, default 1) and page_size (1–15, default 15) to page through results. Every response now includes a metadata object:

{
  "results": [...],
  "metadata": {
    "result_count": 432,
    "page": 1,
    "page_size": 15
  }
}

result_count reflects the total number of matching records for your query. See the pagination guide for details.

Each page is a billable request

Going beyond your initial 15 results requires additional requests. Each page after the first counts as another billable query against your plan. See Billing for details.

April 2, 2026

Fuzzy name matching

Person search now accepts include_fuzzy_matching=true to broaden results with phonetic, nickname, and misspelling matching. See the fuzzy matching guide.

March 26, 2026

Email as a search parameter

Person search now accepts an email address alongside name, phone, and address.

March 25, 2026

Address field breakdown

Address objects in person responses now include discrete fields — line1, city, state, and zip — in addition to the formatted address string.

March 12, 2026

v2 person search and detail endpoints

The v2 person search (GET /v2/person/) and detail (GET /v2/person/{id}) endpoints are now available. v2 responses include enriched data:

current_addresses and historic_addresses as separate lists
match_score — a relevance and completeness score from 1–99
matched_by — which input fields contributed to the match
emails — email addresses with confidence scores

v1 person endpoint deprecation

The v1 person endpoints (GET /v1/person/ and GET /v1/person/{id}) are deprecated. Whitepages will announce a removal date. Migrate to v2 for all new integrations.

February 20, 2026

Webhooks for property deed events

Subscribe to real-time property deed events and receive HTTP POST notifications when deeds record in your target jurisdictions.

POST /v1/webhooks — create a subscription
GET /v1/webhooks — list subscriptions
PUT /v1/webhooks/{id} — update a subscription
DELETE /v1/webhooks/{id} — remove a subscription
POST /v1/webhooks/{id}/test — send a test delivery

See the Webhook Quickstart for setup instructions.

Related

Change Notifications

Breaking Changes Policy

Migration Guides

On this page