--- title: "Search properties by address or APN" method: GET path: "/v3/property/" tags: ["Property V3"] --- # Search properties by address or APN `GET /v3/property/` ## Request - Base URL: `https://api.whitepages.com` - URL: `https://api.whitepages.com/v3/property/` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Search properties by address or by Assessor's Parcel Number. Returns a page of results ordered by how well each matches, with the person lists trimmed and a count of what was held back. Each result links to its full record on the details endpoint. An APN names a parcel rather than describing an address, so an APN search reports no match classification and ignores `strict_match`. `state_code` or `fips` narrows it to one county; a state that does not contain the parcel matches nothing rather than falling back to the number alone. `fips` narrows an address search the same way. Supplying `lat` and `lng` bounds the search to `radius` miles of that point and orders the results by distance, each carrying its `distance_miles`. Address components narrow that set further rather than competing with it. A parcel number names one property outright, so it combines with neither. Nothing matching is a `404` carrying an empty `results` array, so a caller parses one shape either way. It does not bill. A search that filters on `strict_match` or orders by distance decides both over the first 200 candidates, so every page of one query describes one qualifying set in one order rather than one that shifts with the page asked for. Results past that window are not reachable, and `result_count` is held down to what it reaches. A search that neither filters nor reorders pages the index directly and sees no such window. `result_count` saturates at 10,000. A broad query reports that figure rather than a true total, and results past it are not reachable by paging, so narrow the address to reach them. ## Query parameters - `street` string, nullable: Street address line - `city` string, nullable: City name - `state_code` 'AL' | 'AK' | 'AZ' | 'AR' | 'AS' | 'CA' | 'CO' | 'CT' | 'DE' | 'DC' | 'FL' | 'GA' | 'GU' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'MP' | 'OH' | 'OK' | 'OR' | 'PA' | 'PR' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'TT' | 'UT' | 'VT' | 'VA' | 'VI' | 'WA' | 'WV' | 'WI' | 'WY': Valid US State and Territory codes. This enum contains all valid two-letter codes for US states and territories. Used for parameter validation in API requests. - `zipcode` string, nullable: Five-digit ZIP code - `apn` string, nullable: Assessor's Parcel Number. Unique within a county rather than nationally, so it can match several properties. Cannot be combined with address parameters. - `fips` string, nullable: Five-digit county FIPS code. Narrows the search to one county, whether it names a parcel number or an address. - `lat` number, nullable: Latitude of a point to search around. Supply with `lng` - `lng` number, nullable: Longitude of a point to search around. Supply with `lat` - `radius` number, nullable: Radius around the geopoint in miles, defaulting to 1 - `strict_match` boolean, nullable: Keep only results that are the address supplied or an address in the same building - `page` integer: One-based page number - `page_size` integer: Results per page ## Response `200` Properties retrieved successfully - PropertySearchV3ResponseDto: Search response: a page of results plus how to reach the rest. - `results` PropertySearchResultV3Dto[], required - `property_id` string, required: Unique property identifier - `address_id` string, nullable: Unique address identifier - `apn` string, nullable: Assessor's Parcel Number. Unique within a county rather than nationally - `property_address` PropertyAddressV3Dto, required: A property's address, where it has one. Every part is nullable, because a property is not always something with a street address. The next data release publishes about 28 million parcels identified by parcel number and county instead: a house number appears on 1% of them, and a street, city, or ZIP on roughly half. The state is nullable too. The release notes guarantee a parcel number and a county on every property and never make that claim about the state, and a field required on an unverified guarantee is the one that fails on the release that breaks it. Requiring those parts is what keeps those properties out of the API today. Nullable costs a caller a null check; required costs everyone a breaking change on the release that loosens it, which is why it is settled now rather than when the data lands. - `full_address` string, nullable: Complete formatted address string. `null` for a property with no street address - `line1` string, nullable: Street address line (house number and street) - `city` string, nullable: City name - `state` string, nullable: Two-letter state code - `zip` string, nullable: 5-digit ZIP code - `house` string, nullable: House or building number - `street` string, nullable: Street name - `street_type` string, nullable: Street suffix (St, Ave, Blvd, etc.) - `county` string, nullable: County name - `mailing_address` PropertyAddressV3Dto: A property's address, where it has one. Every part is nullable, because a property is not always something with a street address. The next data release publishes about 28 million parcels identified by parcel number and county instead: a house number appears on 1% of them, and a street, city, or ZIP on roughly half. The state is nullable too. The release notes guarantee a parcel number and a county on every property and never make that claim about the state, and a field required on an unverified guarantee is the one that fails on the release that breaks it. Requiring those parts is what keeps those properties out of the API today. Nullable costs a caller a null check; required costs everyone a breaking change on the release that loosens it, which is why it is settled now rather than when the data lands. - `full_address` string, nullable: Complete formatted address string. `null` for a property with no street address - `line1` string, nullable: Street address line (house number and street) - `city` string, nullable: City name - `state` string, nullable: Two-letter state code - `zip` string, nullable: 5-digit ZIP code - `house` string, nullable: House or building number - `street` string, nullable: Street name - `street_type` string, nullable: Street suffix (St, Ave, Blvd, etc.) - `county` string, nullable: County name - `geolocation` GeolocationDto: Geographic coordinates. - `lat` number, required: Latitude coordinate - `lng` number, required: Longitude coordinate - `property_purpose` string, nullable: What the property is used for. Observed values: Amusement, Apartment, Commercial, CondoCommercial, CondoResidential, DuplexTripexQuadplex, Exempt, Financial, Hospital, HotelMotal, Industrial, Office, Parking, Retail, Service, SingleFamilyOrTownhouse, Transport, Vacant, Warehouse. Upstream owns this value space and may send others as the data expands, so match on the values you handle and treat anything else as unrecognized rather than invalid. - `owner_occupied` string, nullable: Whether the owner lives at the property. Observed values: AbsenteeOwner, OwnerOccupied, Unknown. Upstream owns this value space and may send others as the data expands, so match on the values you handle and treat anything else as unrecognized rather than invalid. - `is_vacant` boolean, nullable: Whether the property is currently vacant - `year_built` integer, nullable: Year the property was originally built - `effective_year_built` integer, nullable: Year built adjusted for major renovations - `living_sqft` integer, nullable: Livable square footage - `lot_sqft` integer, nullable: Total lot size in square feet - `ground_floor_sqft` integer, nullable: Ground floor square footage - `basement_sqft` integer, nullable: Basement square footage - `basement_type` string, nullable: Basement type (full, partial, none) - `stories` integer, nullable: Number of stories - `bedrooms` integer, nullable: Number of bedrooms - `bathrooms` integer, nullable: Number of bathrooms - `has_pool` boolean, nullable: Whether the property has a pool - `garage_type` string, nullable: Garage type such as attached or carport - `roof_covering` string, nullable: Roof material type - `heating_fuel` string, nullable: Primary heating fuel type - `condition` string, nullable: Overall property condition - `build_quality` string, nullable: Construction quality rating - `ownership_info` OwnershipInfoV3Dto: Who owns the property, and the terms the ownership was acquired on. Owners are split by entity class rather than collected into one array. A class the data release adds later arrives as a new named field, which is additive, where a new member of a shared array would not be. - `owner_type` string, nullable: Ownership class recorded for the property. A value naming a class with no matching owners field is how a caller learns an owner exists that this version does not break out. Observed values: Business, Individual. Upstream owns this value space and may send others as the data expands, so match on the values you handle and treat anything else as unrecognized rather than invalid. - `person_owners` PersonOwnerV3Dto[]: Individuals who own the property - `id` string, required: Unique person identifier - `name` string, required: Full name - `age` integer, nullable: Age in years - `current_addresses` AddressDto[]: Addresses the person currently lives at - `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 - `phones` PhoneNumber[]: Phone numbers linked to the person - `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. - `emails` PersonEmailDto[]: Email addresses linked to the person - `email` string, required: Email address - `score` integer, nullable: Confidence score 0-100 showing how strongly this email is linked to the person. Higher scores mean a stronger match. - `company_name` string, nullable: Employer name - `job_title` string, nullable: Job title - `result_metadata` PersonResultMetadataV3Dto: Per-person metadata: details link and displayed-vs-additional counts. - `details_url` string, nullable: Canonical Person Details URL for this person, or `null` when the record has no canonical Whitepages person id - `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) - `business_owners` BusinessOwnerV3Dto[]: Business entities that own the property - `name` string, required: Business entity name - `sale_date` string, nullable: Date the property last changed hands - `last_sale_amount` integer, nullable: Amount the property last sold for - `mortgages` MortgageDto[], nullable: Mortgages recorded against the property. `null` on search results; populated on details - `amount` integer, nullable: Mortgage principal amount in USD - `date` string, nullable: Mortgage origination date (YYYY-MM-DD) - `due_date` string, nullable: Mortgage maturity date (YYYY-MM-DD) - `term` integer, nullable: Mortgage term in months - `rate` number, nullable: Interest rate as percentage - `rate_type` string, nullable: Rate type (fixed, adjustable) - `residents` ResidentV3Dto[]: People currently living at the property - `id` string, required: Unique person identifier - `name` string, required: Full name - `age` integer, nullable: Age in years - `current_addresses` AddressDto[]: Addresses the person currently lives at - `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 - `phones` PhoneNumber[]: Phone numbers linked to the person - `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. - `emails` PersonEmailDto[]: Email addresses linked to the person - `email` string, required: Email address - `score` integer, nullable: Confidence score 0-100 showing how strongly this email is linked to the person. Higher scores mean a stronger match. - `company_name` string, nullable: Employer name - `job_title` string, nullable: Job title - `result_metadata` PersonResultMetadataV3Dto: Per-person metadata: details link and displayed-vs-additional counts. - `details_url` string, nullable: Canonical Person Details URL for this person, or `null` when the record has no canonical Whitepages person id - `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) - `assessed_info` AssessedInfoDto: Property tax assessment information. - `market_value` integer, nullable: Estimated market value in USD - `assessed_value` integer, nullable: Tax-assessed value in USD - `property_tax_amount` number, nullable: Annual property tax amount in USD - `property_tax_percent` number, nullable: Effective property tax rate as percentage - `match_score` integer, nullable: Relevance score Search Layer assigned to this result - `distance_miles` number, nullable: Distance from the searched geopoint, in miles. `null` unless the search supplied `lat` and `lng` - `match_type` 'exact' | 'best match': How closely the returned property matches the address asked for. This service derives the value from a digest comparison it performs itself, so no data release can introduce a case it does not handle and the enum is correctly closed. - `confidence_score` integer, nullable: How confident the match is, derived from `match_type` rather than from search relevance - `result_metadata` PropertyResultMetadataV3Dto, required: Per-result metadata: details link and displayed-vs-additional counts. - `details_url` string, required: Canonical Property Details URL for this property - `residents` 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) - `person_owners` 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) - `business_owners` 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) - `metadata` PaginationMetadataDto, required: Pagination metadata returned with every search response. - `result_count` integer, required: Total number of results matching the query - `page` integer, required: Current page number - `page_size` integer, required: Number of results per page ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Nothing matched. Carries an empty `results` array in the same envelope a match would use. - `422`: Unprocessable Content - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-10-23** `e2dc46cff897`: 1 info - endpoint added [Operation history](https://skmtc.dev/whitepages/apis/whitepages-api-reference/changes/v3/property/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)