browse_leads

club.goodleads/new-business-owner-contacts · Verify this server

Browse leads — rows for a shape or a saved list, or (`summary=True`) its counts, facets and price. Two ways to say which records, one contract underneath: * a saved list — `list_id`, the 8-char id in `#browse?list=<id>`. Its states, filters, sort and inactive-or-holding toggle are read from the list; pass nothing else about the shape. * an inline shape — `filters` plus `state` (one state) or `states` (several); omit both for every live state (CO, CT, FL, NY, TX, VA). `summary=True` returns the summary contract instead of rows — the same numbers the buying surface shows, from the same code path: `matching`, `sellable`, `verified_one`, `verified_both`, `no_channel`, `unnamed`, `facets`, `prices`, `quote` (present when `lane` or `cap` is given), `exact`, `computed_at`, `quote_valid_until`, `per_state`. **Only `sellable` — a matching record whose filing names a person — is ever billed or delivered; never quote `matching` as a price.** name and address $0.25 per record · plus one verified phone or email $0.50 · plus both $0.70 (price rule v1; live prices always come from the summary call's `prices` block). Lanes: `all` / `best` / `contact` (`all` = every sellable record at the name-and-address price; `best` = each record at its own grade, verified first; `contact` = only records with a verified phone or email). Cap: `{"type": "count|budget", "value"}` — records for count, cents for budget. To buy, hand the same list / shape, lane and cap to `create_checkout`. Speak the canonical vocabulary — it is the same across every state: `status` and `entity_type` take canonical values (`"active"`, `"LLC"`), so `entity_type = "LLC"` matches Colorado's raw `DLLC`, Florida's `FLAL`, and New York's spelled-out form alike; state-specific raw codes live behind `status_raw` / `entity_type_raw` if you ever need them. "Contacts for new businesses" / "decision-makers" = filter `contact_relevance_tier in ["Decision Maker", "Likely Decision Maker"]` — our scored is-this-the-right-person opinion, available in EVERY state. (`role_is_decision_maker: true` is the stricter, title-attested variant: it means the state's own filing lists an authority title. Several states — Colorado and New York among them — publish no officer titles at all, so filtering on it there returns zero and silently drops real decision-makers. Layer it on top only when you specifically want title-attested records.) When a filter touches a (field, value) the requested state never populates by design (e.g. `entity_type="SOLE_PROP"` in TX), the payload additionally carries `zero_reasons` — machine-readable notes saying WHY the count is zero and the nearest alternative; the key is absent otherwise. Add `has_phone` / `has_email` for reachable ones. Worked example — active LLC decision-makers with a phone, across all states, excluding two sectors: browse_leads(filters=[ {"field": "status", "op": "eq", "value": "active"}, {"field": "entity_type", "op": "eq", "value": "LLC"}, {"field": "contact_relevance_tier", "op": "in", "value": ["Decision Maker", "Likely Decision Maker"]}, {"field": "has_phone", "op": "eq", "value": true}, {"field": "industry_sector", "op": "not_in", "value": ["Real Estate", "Finance"]}, ]) Filter grammar (rendered from the schema — `list_filterable_fields(section="grammar")` is the full contract): a leaf is `{"field", "op", "value"}`; the top-level filters list is an implicit `and` group; group nodes `{"op": "and", "filters": [...]}` and `{"op": "or", "filters": [...]}` nest one or more children, `{"op": "not", "filters": [<one leaf or group>]}` negates exactly one. Operators by field type — text: eq, neq, in, not_in, contains, does_not_contain, exists, missing; number: eq, neq, gt, gte, lt, lte, between, in, not_in, exists, missing; date: eq, neq, gt, gte, lt, lte, between, in, not_in, exists, missing; boolean: eq, neq; geo: within. Narrower pseudo-fields — `run_manifest_id` eq; `missing_stage` eq; `created_at` gt, gte, lt, lte, between; `geo_polygon` within; `geo_radius` within; `has_phone_or_email` eq. `neq`, `not_in`, `does_not_contain`, `not` keep rows where the field has no value. `exists` / `missing` take no value; `in` / `not_in` take a non-empty list; `between` takes `[start, end]`, both required. A (field, op) pair outside its type's row is a 422 naming the row, never a 500. Records appear here the morning after the state posts them — speed is measured from publication, never from filing. Args: state: Two-letter state code (e.g. `FL`, `CO`) for one state. states: Several state codes (rows or summary). Omit both `state` and `states` for every live state. list_id: A saved list id. Mutually exclusive with `state` / `states` / `filters` — the list already carries them. filters: Filter clauses in the grammar above (leaves and `and` / `or` / `not` groups). Use `list_filterable_fields` to discover the 77 fields, each one's enforced operators and allowed values. page: 1-based page number. page_size: Rows per page (1–200 with a key; capped at 25 on the free tier, default 50). sort: `[{"field", "dir"}]`, one or more keys over any of the 71 sortable fields (`asc` / `desc`); a bare field name still works with `sort_dir`. Tier fields sort by rank (reachability_tier On Fire > Very Hot > Hot > Warm > Cold; contact_relevance_tier Decision Maker > Likely Decision Maker > Probable Contact > Uncertain Contact > Unlikely Decision Maker; contact_confidence_tier Verified Contact > Likely Contact > Possible Contact > Uncertain Contact; industry_confidence_tier confirmed > likely > possible > unknown); lead_ref ASC is always appended (total order). An unknown field or direction is a 422 listing the sortable fields — never a silent fallback. Default `reachability_score` descending. sort_dir: `asc` or `desc` (default `desc`) — used when `sort` is a bare field name. include_non_operating: Include inactive or holding businesses (default False — only the records we sell). A saved list's own toggle wins when `list_id` is given. summary: Return the summary contract (counts, facets, prices, quote) instead of rows. Implied when `lane` or `cap` is given. lane: `all` / `best` / `contact` — asks the summary for a `quote`. cap: `{"type": "count|budget", "value": <int>}` — the dial the quote is solved against (records for count, cents for budget). Returns: Rows: `{"items": [...], "total", "page", "page_size", "pages", "access_level", "_meta"}`. `_meta` is the provenance block every read carries: `schema_version` (the read-contract version — pin migrations to it), `freshness.data_refreshed_at` (when this state's data was last worked), `source` (public registry + derived-field attribution), `score_versions`, and `access_level` (preview = masked contacts, full = keyed). Keyless callers see `contact_name`, `email_primary`, `phone_primary` masked and may not filter the summary on them (422). Summary: the contract described above.