Property Search API

The Property Search API returns ownership and resident information for a given property. Use it to identify property owners, find current residents, or verify property details.

Make your first request

Send a request

Search for property details by address:

Request

curl 'https://api.whitepages.com/v2/property/?street=STREET_ADDRESS&city=CITY&state_code=STATE_CODE' \
  --header 'X-Api-Key: YOUR_API_KEY'

Replace YOUR_API_KEY with your actual API key, and replace STREET_ADDRESS, CITY, and STATE_CODE with the address of the property you want to look up (URL-encode any spaces).

Review the response

A successful request returns property details with owner and resident information:

Response

{
  "result": {
    "property_id": "RSAMPLE0001",
    "address_id": "ASAMPLE0001",
    "apn": "197500-0015",
    "property_address": {
      "full_address": "123 Main Street, Seattle, WA 98101",
      "line1": "123 Main Street",
      "city": "Seattle",
      "state": "WA",
      "zip": "98101",
      "house": "123",
      "street": "Main",
      "street_type": "Street",
      "county": "King"
    },
    "mailing_address": {
      "full_address": "PO Box 4242, Bellevue, WA 98009",
      "line1": "PO Box 4242",
      "city": "Bellevue",
      "state": "WA",
      "zip": "98009",
      "house": "4242",
      "street": "PO Box",
      "street_type": null,
      "county": "King"
    },
    "property_purpose": "SingleFamilyOrTownhouse",
    "owner_occupied": "OwnerOccupied",
    "is_vacant": false,
    "geolocation": {
      "lat": 47.60621,
      "lng": -122.33207
    },
    "ownership_info": {
      "owner_type": "individual",
      "sale_date": "2014-06-25",
      "business_owners": [
        { "name": "Acme Holdings LLC" },
        { "name": "Sample Trust" }
      ],
      "person_owners": [
        {
          "id": "PSAMPLE0001",
          "name": "John Smith",
          "age": 54,
          "current_addresses": [
            {
              "address_id": "ASAMPLE0001",
              "full_address": "123 Main Street, Seattle, WA 98101",
              "line1": "123 Main Street",
              "city": "Seattle",
              "state": "WA",
              "zip": "98101"
            }
          ],
          "phones": [
            { "number": "(206) 555-0142", "type": "mobile", "score": 95 },
            { "number": "(425) 555-0188", "type": "landline", "score": 68 },
            { "number": "(206) 555-0177", "type": "mobile", "score": 54 },
            { "number": "(360) 555-0121", "type": "voip", "score": 31 }
          ],
          "emails": [
            { "email": "john.smith@example.com", "score": 88 },
            { "email": "j.smith@example.org", "score": 52 },
            { "email": "jsmith@example.net", "score": 44 }
          ],
          "company_name": "Acme Holdings LLC",
          "job_title": "Operations Manager",
          "person_owner_metadata": {
            "details_url": "/v2/person/PSAMPLE0001",
            "phones": { "displayed": 4, "additional": 3 },
            "emails": { "displayed": 3, "additional": 1 },
            "owned_properties": { "displayed": 1, "additional": 3 }
          }
        },
        {
          "id": "PSAMPLE0011",
          "name": "Jane Smith",
          "age": 51,
          "current_addresses": [
            {
              "address_id": "ASAMPLE0001",
              "full_address": "123 Main Street, Seattle, WA 98101",
              "line1": "123 Main Street",
              "city": "Seattle",
              "state": "WA",
              "zip": "98101"
            }
          ],
          "phones": [
            { "number": "(206) 555-0143", "type": "mobile", "score": 91 }
          ],
          "emails": [{ "email": "jane.smith@example.com", "score": 76 }],
          "company_name": null,
          "job_title": null,
          "person_owner_metadata": {
            "details_url": "/v2/person/PSAMPLE0011",
            "phones": { "displayed": 1, "additional": 0 },
            "emails": { "displayed": 1, "additional": 0 },
            "owned_properties": { "displayed": 1, "additional": 0 }
          }
        }
      ]
    },
    "residents": [
      {
        "id": "PSAMPLE0001",
        "name": "John Smith",
        "age": 54,
        "current_addresses": [
          {
            "address_id": "ASAMPLE0001",
            "full_address": "123 Main Street, Seattle, WA 98101",
            "line1": "123 Main Street",
            "city": "Seattle",
            "state": "WA",
            "zip": "98101"
          }
        ],
        "phones": [
          { "number": "(206) 555-0142", "type": "mobile", "score": 95 },
          { "number": "(425) 555-0188", "type": "landline", "score": 68 },
          { "number": "(206) 555-0177", "type": "mobile", "score": 54 },
          { "number": "(360) 555-0121", "type": "voip", "score": 31 }
        ],
        "emails": [
          { "email": "john.smith@example.com", "score": 88 },
          { "email": "j.smith@example.org", "score": 52 },
          { "email": "jsmith@example.net", "score": 44 }
        ],
        "company_name": "Acme Holdings LLC",
        "job_title": "Operations Manager",
        "resident_metadata": {
          "details_url": "/v2/person/PSAMPLE0001",
          "phones": { "displayed": 4, "additional": 3 },
          "emails": { "displayed": 3, "additional": 1 },
          "owned_properties": { "displayed": 1, "additional": 3 }
        }
      },
      {
        "id": "PSAMPLE0013",
        "name": "Emily Smith",
        "age": 23,
        "current_addresses": [
          {
            "address_id": "ASAMPLE0001",
            "full_address": "123 Main Street, Seattle, WA 98101",
            "line1": "123 Main Street",
            "city": "Seattle",
            "state": "WA",
            "zip": "98101"
          }
        ],
        "phones": [
          { "number": "(206) 555-0144", "type": "mobile", "score": 84 }
        ],
        "emails": [{ "email": "emily.smith@example.com", "score": 71 }],
        "company_name": null,
        "job_title": null,
        "resident_metadata": {
          "details_url": "/v2/person/PSAMPLE0013",
          "phones": { "displayed": 1, "additional": 0 },
          "emails": { "displayed": 1, "additional": 0 },
          "owned_properties": { "displayed": 0, "additional": 0 }
        }
      }
    ],
    "property_metadata": {
      "confidence_score": 100,
      "match_type": "exact",
      "details_url": "/v2/property/RSAMPLE0001"
    }
  }
}

The response includes the matched property with geolocation, property owners, and current residents, plus a property_metadata block describing how well the property matches the address you searched for.

Match confidence

Search ranks properties by how closely they match the address text you send, so the closest match to an address that does not exist can be a different property on the same street. Every response carries a property_metadata block saying what you actually 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:

Score	Meaning
`100`	The property is the address you searched for
`90`	A different unit in the same building
`50`	The closest match found, at a different address
`25`	The address you searched for is not a deliverable address
`null`	The address could not be checked

The score compares standardized addresses rather than measuring search relevance, so it answers "is this the property I asked for" rather than "how well did this rank".

confidence_score and match_type are null when the address cannot be standardized — most often because the request carried no street, or carried a street with neither a city nor a zipcode to place it. The property is still returned.

Returning only exact matches — `strict_match=true`

If a wrong property is worse than no property — an automated pipeline, say, or address verification — set strict_match=true. The API returns the address you searched for or an address in the same building, and 404 when it finds neither.

Request

curl 'https://api.whitepages.com/v2/property/?street=123%20Main%20Street&city=Seattle&state_code=WA&strict_match=true' \
  --header 'X-Api-Key: YOUR_API_KEY'

A result the API cannot verify is also dropped, because strict matching promises nothing approximate comes back. strict_match needs a street to compare against; a request without one returns 400.

Contact limits on owners and residents

Each owner and resident carries up to 4 phone numbers and 3 email addresses, highest confidence first. A metadata block on each person reports what was held back and where the rest lives:

"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 (phones: 4, emails: 3). The full lists are always available via details_url at /v2/person/{id}. Owners carry person_owner_metadata and residents carry resident_metadata; the contents are identical.

owned_properties.additional counts other properties the person owns, bounded by how many the search can retrieve at once. A person who owns a large portfolio reports fewer than they hold. Phone and email counts are exact.

Request parameters

Parameter	Required	Description	Example
`street`	No*	Street address	`123 Main Street`
`city`	No*	City name	`Seattle`
`state_code`	No*	Two-letter state code	`WA`
`zipcode`	No*	ZIP code	`98101`
`strict_match`	No	Return only the address supplied or one in the same building	`true`

At least one parameter is required. Include multiple parameters for more precise results.

Example with ZIP code:

https://api.whitepages.com/v2/property/?street=123%20Main%20Street&zipcode=98101

Example by property ID:

https://api.whitepages.com/v2/property/RSAMPLE0001

Property details by ID

The property details endpoint 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 pass the address IDs found throughout other API responses directly:

https://api.whitepages.com/v2/property/{property_id_or_address_id}

Not every address ID has full property details, so lookups by address ID may return 404. These responses are not billed — see Billing — so you can optimistically look up property details for any address ID you encounter.

Address standardization

Property addresses (both physical and mailing) are not processed through CASS certification. Property address data is sourced directly from county assessor and recorder records and is stored as-received without USPS standardization.

The address you search with is standardized, so that the response can tell you whether the property returned is the one you asked for. That standardized form is used only for the comparison behind property_metadata and strict_match — it never changes the address values in the response, which remain as the county recorded them.

For person address standardization details, see Search by Address.

What's next

You've completed the getting started tutorials. Explore the References section for complete API documentation.

Search for property by address

Search for property by address parameters. Returns basic property information including property_id, address, owner, and resident details. For comprehensive property details including physical characteristics, tax assessments, and mortgage history, use the returned property_id with the "Get property details by ID" endpoint (/v2/property/{property_id}). 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; it needs a street to match against, so a request setting it without one is rejected.

Get property details by ID

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 before lookup. This endpoint returns comprehensive property data including physical characteristics, tax assessment information, ownership details, mortgage history, predictive insights, and current residents. To obtain a property_id, first use the "Search for property by address" endpoint (/v2/property/), which returns basic property information including the property_id needed for this request.

Capability Map

Map a user's intent to the exact endpoint and parameters that answer it.

Search by Address

Find people by current or historical addresses