API Reference › Property Search

Build a Lead List

POST /v1/api/property-search/execute/

Cost: 5 credits per row delivered.

Rate limit: 500 property searches per minute per account.

Mode: Async: returns a lead list ID, rows arrive by webhook and the rows endpoint.

Create a lead list and dispatch the build task. This is the charged path, 5 credits per *delivered* row. Returns a 202 with the new id and a poll_url. The build runs asynchronously and typically takes 1-5 minutes depending on requested_count. Poll the status endpoint until completion, or configure your account webhook to get notified automatically. Related endpoints: Get Lead List Status · Get Lead List Rows · Property Lookup

Fields

strategy: Same as /preview/. Defaults to 'custom'.
geography (required): Same shape as /preview/.
filter_overrides: Same shape as /preview/.
requested_count (required): 1-25000. Billed at 5 credits per delivered row, capped here.
name: Optional label shown in /lead-lists/ and the status response.
exclude_all_previous_properties: When true, the list skips every property already delivered to your account in any earlier list, whatever filters that list used. Billed at the same 5 credits per delivered row. The build scans the search in the background until it has requested_count new properties; if the search runs out first, the list comes in under your requested count and you are only billed for delivered rows. Searches matching more than 1,000,000 properties are rejected with this option; narrow the search first. Defaults to false.
dedupe_from_history: When true, the build excludes any propertyId your account has previously received from a past /execute/ call that used the same filter set (strategy + geography + filter_overrides). Useful for re-runs when you only want fresh leads. The match is hash-based, multi-strategy slug order and geography list order are normalized. To keep upstream cost bounded, the build fetches up to 5× requested_count properties before truncating; if your filter pool is mostly exhausted, the final list may come in under your requested count (actual_count < requested_count) and you are only billed for delivered rows. Defaults to false (no exclusion).

Responses

202: Success.
400: Validation error
402: Insufficient credits
403: Account suspended (unpaid invoices)
429: Rate limit reached: 500 property searches per minute per account.