API Reference › Property Search

Preview a Search

POST /v1/api/property-search/preview/

Cost: Free.

Rate limit: 500 property searches per minute per account.

Mode: Sync

Preview a lead list before charging. Returns the total match count, the capped count (the lower of total_matches and your requested_count), and the maximum credit cost. Preview calls do not charge credits. Use this to iterate on filters and geography before committing, safe to call repeatedly. Rate limited to 500 property searches per minute per account. About max_credit_cost: 5 credits per row in the delivered CSV. The value is the ceiling, if fewer properties match than requested_count, capped_count drops and the charge drops with it. Filters: see List Filters for preset strategies, or use 'custom' and supply individual filters via filter_overrides. Full key reference at Filter Reference. Geography modes: zips, city, counties, states, radius. See the shape examples under the geography param below. Related endpoints: Build a Lead List · Get Lead List Status · Get Lead List Rows

Fields

strategy: Strategy key from /filters/. Defaults to 'custom'. Supports comma-separated multi-select (e.g. 'pre_foreclosure_motivated,probate_inherited,vacant') to combine multiple lead types with OR logic.
geography (required): Geography dict with a required mode field. Shapes: - {"mode": "zips", "zip_codes": ["85001","85004"]} - {"mode": "city", "cities": ["Phoenix"], "states": ["AZ"]} - {"mode": "counties", "counties": ["Maricopa"], "states": ["AZ"]} - {"mode": "states", "states": ["AZ","TX"]} - {"mode": "radius", "latitude": 33.45, "longitude": -112.07, "radius": 5} (miles)
filter_overrides: Filters merged on top of the strategy defaults. See Filter Reference for every accepted key.
requested_count (required): Maximum rows you'd pay for. 1-25000. capped_count in the response = min(total_matches, requested_count).
include_pins: When true, the response also includes up to 500 {latitude, longitude} pins for map rendering. Defaults to false for API callers who don't need them.
exclude_all_previous_properties: When true, the build skips every property already delivered to your account in any earlier list, whatever filters that list used. The preview count is still before this exclusion, so the response adds exclude_all_previous_properties (echoes the flag), count_before_history_exclusion, history_exclusion_pending, account_wide_exclusion_allowed and account_wide_exclusion_max_matches. Searches matching more than 1,000,000 properties cannot use this option. Defaults to false.
dedupe_from_history: When true, the response returns the post-dedupe count: properties this account has already received from past /execute/ calls with the same filter set are subtracted. The response gains three extra fields: dedupe_from_history (echoes the flag), excluded_from_history (how many propertyIds would be skipped), and available_after_dedupe (the new effective pool size). Defaults to false. Same-filter matching is hash-based and ignores click order of multi-strategy slugs and geography lists.

Responses

200: Preview with dedupe_from_history=true
400: Unknown strategy
429: Rate limit reached: 500 property searches per minute per account.
503: Upstream temporarily unavailable