Browse leads — rows for a shape or a saved list, or (`summary=True`) its counts, facets and price.
**Type it the way your buyer says it.** Filter values are understood, not matched literally: "residential",
"cell", "CST", "Texas", "on fire", "Denver metro" and "working from home" all resolve (case, spacing, plurals and
reviewed words), and every response echoes what was understood in `interpreted_values` (typed → stored). A value
that matched nothing comes back with `value_hints` — the closest real values and, for a closed list, every allowed
value. Read both before telling a human a count is zero or a field is missing.
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, OR, 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 `checkout_list`.
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" is the buyer's word for the records themselves — every record
names a person, so "contacts for new salons" needs no extra filter.
"Decision-makers" = filter
`contact_relevance_tier in ["Decision Maker", "Likely Decision Maker"]` —
our scored is-this-the-right-person opinion, available in EVERY state;
apply it when the buyer asks for decision-makers, never silently.
(`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. A
`formation_date` window that holds nothing explains itself the same way
on a summary: whether it ends before our earliest matching record, and
what the same filters match without the date limit.
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"]},
])
`filing_kind` says what the state filing did. The default is Just started
(`formation`) — a business that did not exist before its filing — so a plain
call never returns an existing business that the state gave a new document
number. Widen with `include_existing=True` (every existing business with a
new filing at once) or by name: `filing_kind in ["registration", "conversion",
"name_change", "reinstatement", "address_change"]` returns existing businesses
the state published a fresh event about; `lead_class` on every row carries
the answer in the buyer's words — `Just started`, `New to <state>` (the
record's own state), `Established business, new entity`, `New trade name`,
`Back in business`, `Moved`. Never mix the two in one order — they are priced and
sold as separate lists. Closed businesses (`dissolution`) are excluded unless
named or `include_non_operating=True`. Every row also carries `last_event`
and `last_event_date` — the most recent thing the state published and the day
it published it.
Same owner: `cluster_size >= 2` is every business whose owner filed more
than one, so one call reaches the set; `cluster_code` is the record's place
in that group (`XF-O` / `XP-O` / `XM-O` an operating business, the `-V` codes
a holding company built around one). Blank on a single, so a filter on either
never matches a business with no related filing. `new_business_tier`
(`Confirmed new` … `Established`, newest first) is how sure we are the
business is genuinely new — filter on it, never sort by it; an empty result on
a fresh cohort means the score has not reached it yet.
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; `cluster_ref` eq; `missing_stage` eq; `created_at` gt, gte, lt, lte, between; `geo_polygon` within; `geo_radius` within; `has_phone_or_email` eq; `filing_kind` eq, neq, in, not_in; `new_business_tier` eq, neq, in, not_in. `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
86 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 77 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; new_business_tier Confirmed new > Likely new > Uncertain > Likely established > Established); 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.
include_existing: Include existing businesses with a new filing —
opening a location here, formed in another state, back in
business, a new entity, moved, a new trade name (default False —
Just started only). Naming a `filing_kind` implies it.
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).
group_by: Up to two fields to cross-tab the summary by, e.g.
`["property_classification", "naics_2_digit"]` — residential vs.
commercial by industry in ONE call. Adds a `groups` block: the
four counts and the `share` per group, the top 50 groups, the rest
rolled into `other`. Groupable — classification: industry_sector,
industry_name, naics_2_digit … naics_6_digit, sic_2_digit …
sic_4_digit, gmb_category, mcc; geography: state, msa_name,
county_fips, principal_city, principal_zip, neighborhood,
time_zone, tract_income_band; also property_classification,
entity_type, reachability_tier, filed_by, formation_month.
Records our pipeline has not classified read `Unclassified`: counted with the groups so rows add up, ranked last (never leading a "largest" list), with the classified share in `classification` — the
classifier places more of them on every pipeline run, so a repeat
call later is a better count. Implies `summary=True`.
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`, `registered_agent_name` masked and may not filter the summary on them (422).
Summary: the contract described above.