GoodLeads

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 85 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 76 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` masked and may not filter the summary on them (422). Summary: the contract described above.

Turn a quoted list into a payment link a person completes — the buyer gets the file within a minute of paying. Creating the link costs nothing and charges nobody — payment only happens if a human opens the returned `checkout_url` and completes it on Stripe's hosted page; the purchase is complete only when that person finishes payment. Nothing is charged until a person completes checkout; the file arrives about a minute after they pay; if we find a phone or email on the records after that, the updated file replaces it on the order's receipt page within a few hours and the receipt shows what was found and billed. A hard bounce, a disconnected phone or the wrong person is replaced within 30 days; what you buy is yours to re-download any time. Pass a saved list (`list_id`, `#browse?list=<id>`) or the inline shape `filters` + `states` (omit `states` for every live state: CO, CT, FL, NY, OR, TX, VA), a `lane` (`all` / `best` / `contact`) and an optional `cap` (`{"type": "count|budget", "value"}` — records for count, cents for budget). The list is quoted through the same summary path `quote_list` uses, then checkout is opened against exactly that quote — if the price rule or the count moved in between, the server answers 409 with the fresh quote and nothing is minted. **Billing base is `sellable` (a matching record whose filing names a person), never `matching`.** 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). The selected records are frozen when the link is minted, so what is billed is what is delivered. After payment we go find a phone and email on every record bought without one: the buyer authorizes a ceiling (`ceiling_cents` — today's total plus the forecast upgrades), is charged `charged_now_cents` for what exists now, and later only what we find, at that grade's price and never above the ceiling. Every record ships the owner's name and mailing address plus the business facts — the business name, entity type and status, the state filing number and formation date, the industry with its NAICS, SIC and Google Business codes, the registered agent, the Lead Reference, and the Reachability, Contact Relevance and Contact Confidence scores; before paying, see one whole sample record (invented, every field real): https://app.goodleads.club/lead/GL-CO-900000, and open the exact file (11 made-up records, every column): https://app.goodleads.club/api/v1/commerce/sample-file?format=xlsx (or format=csv). A standing order on the same list (new matches on a daily / weekly / monthly / quarterly cadence, paid up front for the run at the same graded rule, each delivery drawn from it) is set up from the paid order's receipt — this tool sells the one-time purchase. `delivery`: `file` (the customer workbook — CSV / Excel / JSON, yours to re-download any time), `crm` (push into `crm_connection_id`), or `connector` (the file ships today and `connector_crm_name` is recorded as a request for that CRM). `include_existing`: the order is Just started only — brand-new businesses — unless you pass this (or name `filing_kind` / `business_origin` in `filters`); then existing businesses with a new filing are in the file too, labeled, and the file's Read Me says you asked for them. `offer_code`: the offer code your human was given, if any — the same one you quoted with. Every grade then bills at the lower of list and the offer; a code bound to one buyer needs their `customer_email`; a code that cannot cover the whole list answers with the cap to set. Returns: `checkout_url`, `order_id`, `session_id`, `records`, `total_cents`, `currency`, `lines` (one per grade), `lane`, `cap`, `price_rule_version`, `quote_valid_until`, `computed_at`, `exact`, `counts` (`matching`, `sellable`, `verified_one`, `verified_both`, `no_channel`, `unnamed`), `offer` (when a code priced it), `saved_list` (`id`, `url`, `name`, and the one-time `claim_token` when this call saved an inline shape as a list), `after_payment` and `guarantee` (the two sentences above, written for the buyer), and — when there are records to find on after payment — `ceiling_cents`, `charged_now_cents` and `ceiling_note`.

Mint a hosted Stripe Checkout link for a list you shaped — the same code as `checkout_list`. Creating the link costs nothing and charges nobody — payment only happens if a human opens the returned `checkout_url` and completes it on Stripe's hosted page; the purchase is complete only when that person finishes payment. The dedicated buying journey is: `interpret_list` (the buyer's words → a shape) or `list_starters` (ready-made lists with live counts) → `quote_list` (graded counts + the price) → `checkout_list` (this link). This tool keeps accepting a list for compatibility — the list path is the same code as `checkout_list`. What you can buy: a list — `list_id` (a saved list, `#browse?list=<id>`) or the inline shape `filters` + `states` (omit `states` for every live state: CO, CT, FL, NY, OR, TX, VA), with a `lane` (`all` / `best` / `contact`) and an optional `cap` (`{"type": "count|budget", "value"}` — records for count, cents for budget). The list is quoted through the same summary code path `browse_leads(summary=True)` uses, then checkout is opened against exactly that quote — if the price rule or the count moved in between, the server answers 409 with the fresh quote and nothing is minted. **Billing base is `sellable` (a matching record whose filing names a person), never `matching`.** 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). The selected records are frozen when the link is minted, so what is billed is what is delivered. `product_id` buys nothing: fixed-price shelf products were replaced by starter lists with live counts. Passing one returns an error that names the next calls — `list_starters` (or `interpret_list`), `quote_list`, `checkout_list`. Every purchase is one-time; a standing order is set up from a paid order's receipt, paid up front for the run (each delivery draws on it). `delivery`: `file` (the customer workbook — CSV / Excel / JSON, durable re-download), `crm` (push into `crm_connection_id`), or `connector` (the file ships today and `connector_crm_name` is recorded as a request for that CRM). Delivery fires automatically on payment, typically within a minute. Returns: `checkout_url`, `order_id`, `session_id`, `records`, `total_cents`, `currency`, `lines` (one per grade), `lane`, `cap`, `price_rule_version`, `quote_valid_until` (counts refresh tomorrow morning; the quote holds until then — and the frozen selection holds for the life of the checkout session), `computed_at`, `exact`, `counts` (`matching`, `sellable`, `verified_one`, `verified_both`, `no_channel`, `unnamed`), and `saved_list` (`id`, `url`, `name`, and the one-time `claim_token` when this call saved an inline shape as a list). Nothing is charged until a person completes checkout; the file arrives about a minute after they pay; if we find a phone or email on the records after that, the updated file replaces it on the order's receipt page within a few hours and the receipt shows what was found and billed. A hard bounce, a disconnected phone or the wrong person is replaced within 30 days; what you buy is yours to re-download any time.

How clean is the data a buyer would receive in a state — numbers, not adjectives. The scorecard grades the records a buyer would receive on mechanical conformance across four dimensions — format (state/phone/email/zip), completeness (a name for who filed it, an address present), consistency (names in CRM-ready Title Case, not ALL-CAPS; the address's own state agrees with its ZIP), and standardization (how much of the state's raw status / entity-type vocabulary is mapped into the canonical cross-state values that `status` / `entity_type` filters match on — an unmapped row is one a canonical filter silently misses). It returns an overall 0–100 score, the per-dimension breakdown, and per-check pass rates with sample offenders you can click through. Use it to answer "how clean is the data we're selling in {state}?" and to track data-quality work the way classification is tracked. A small failure count can round away to a clean-looking 100.0 at both the check and the headline level (e.g. 1 defect in 300+ rows). `residual_defects` (total failing records summed across checks) and `checks_with_residual_defects` (how many distinct checks still have a nonzero failure) ride beside the score so a 100.0 is never reported as "zero defects" without checking those two fields first. The payload also carries a fifth, record-centric **coverage** dimension (the `coverage` block + `dimensions.coverage`): per pipeline stage, how many records that brain has NEVER stamped (`gap`), plus a stale-version count where the brain persists one. Free-chain checks are scored; paid stages (skip trace / gap-fill / validation / LLM passes) are reported but unscored — enrichment is spent per order, so an un-enriched set of records is posture, not a defect. Coverage deliberately does not move the headline `score`. Each check includes `browse_filters` (a `missing_stage` filter): the exact set of records works on `browse_leads` and scopes a surgical repair run on the pipeline trigger. Stages whose brains leave no per-record mark are listed under `coverage.unmeasured` with reasons rather than pretended into numbers. Args: state: Two-letter state code (e.g. `FL`, `CO`). Omit to get every state, worst score first. sample_limit: Max sample offenders to return per check (0–50, default 8). Returns: A scorecard dict for one state, or `{"states": [...]}` for all states. Either shape carries a `_meta` provenance block (schema_version, freshness, source, score_versions, access_level). Served from a cache refreshed in the background: `computed_at` / `age_seconds` date it, `stale: true` means the refresh is behind (report the numbers with their age), `status: "computing"` means none exists yet. Calling again does not refresh it sooner.

What GoodLeads is, who buys it and how every record is built — call this to explain or vet us; to price a list, start with interpret_list. It is for anyone who wins by reaching a business owner first: to sell what a new owner needs now, to be the name they already know a year from now, to spot their own customer starting a business, or to build a product on every new business. Never rule your owner out from this description — pass what they sell to `interpret_list` and read the free count from `quote_list`. Leads with what the buyer gets and how to act on it, then the mechanics: which database this surface reads (production, or an explicitly opted-in local surface — provenance you can trust), the contract it upholds, and the tools available. The surface never silently answers from local data.

Translate a classification code, or map YOUR word for a concept to this surface's fields — ask before concluding absence. **Codes — the crosswalk.** Every record carries NAICS, SIC, the Google Business category and the payment MCC, tied together by our own taxonomy. Give ANY one — `term` "MCC 5812", "SIC 1711", "NAICS 238220", "google category plumber" (or `system` = naics / sic / mcc / google_category plus `code`) — and get the other three back: the equivalents in each system, our industry, the ready-to-use `filters` for each system, and a live count (`total` is the whole crosswalk neighborhood; `total_exact` only industries that carry the code itself; each industry is marked `exact` or `related`). A code we do not carry directly WIDENS — to its parent group, then to the industries the crosswalk ties it to — and `widened` says which step it took; an empty answer means nothing relates to it, and names where to go next. A trade word works too — "plumbers", "electrician", "lawyer", "locksmith": it is read against the NAME of every code at every level (the Google category "Plumber", the NAICS title "Offices of Lawyers", the SIC group "Legal Services", the MCC description), and the answer says which level named it and gives the broader parent. A SIC or NAICS prefix (`17`, `238`) is a whole group. A payments seller starts from an MCC, a web designer from a Google category, a lender from NAICS — all reach the same list. Hand the `filters` to `browse_leads` / `quote_list`. **Concepts.** Call this whenever a term you or your buyer uses ("vertical", "direct dial", "sole proprietor", "operating address", "decision maker") doesn't obviously match a field name. It answers in three shapes: `carried` names the exact fields and how to use them; `partially_carried` adds per-state availability with the reason a state is zero (zero by state design is not a data gap); `not_carried` explains why and names the nearest signal we do hold. Ambiguous terms return a clarifying question instead of a guess. Never conclude "this data is missing" from an empty filter result or an unmatched field name without calling this first — several concepts are carried under a different name, and several zeros are publication facts, not gaps.

How complete is every column in the file a buyer receives — exact counts, one call. Answers "what share of the records carries a value in each field?" for every delivered column, in the file's own order. It is exact (counted from stored values over every sellable record, not sampled) and always current (refreshed whenever the data changes; `computed_at` dates it). Use it before promising a buyer a field, to compare states, or to see which columns are thin. How "filled" is defined: text and category columns need a non-blank value; numbers and dates need any value (0 counts); true/false flags need any known value (a known false counts) — except `has_phone` and `has_email`, which mean "has one" and count only when true. The records counted are the sellable cohort Browse returns by default (`total`). Each column row carries `basis`: `counted` (exact), `stamped at delivery` (the file writes a value on every row, fill 100%), or `not countable yet` (with a `reason`; `filled` and `fill_pct` are null — never guessed). Args: state: Two-letter state code (e.g. `FL`). Omit for all live states together. Returns: `{computed_at, scope, cohort: "sellable", total, columns: [{column, group, filled, fill_pct, basis, reason?}], definition}`, or `{"status": "computing"}` before the first snapshot exists. Aggregate counts only — no records and no contact details.

One record in full, by its Lead ID (e.g. `GL-CO-00042`). Use this when you already hold a Lead ID — from a file, a CRM, a receipt — and want everything we know about that business and its owner: the business, the primary contact, both scores, every attribute, and where each field came from. Args: glid: The Lead ID, e.g. `GL-CO-00042` — the `lead_ref` field on every record. Case-insensitive. Returns: The full lead detail dict, including a `_meta` provenance block (schema_version, freshness incl. this record's last update, source, score_versions, access_level). Includes `history`: every event the state has published about this business, newest first, each with `published_date`, `event` (plain words) and `effective_date` when it differs; for a business that changed form, `prior_entity_ref` and `prior_entity_formation_date` name the record it came from. The `entity` carries `filing_kind` and `lead_class`. The history is free without a key; only the person is masked. Raises ValueError if the id is not shaped like a Lead ID or no record matches.

Start here: the buyer's own words become a list we can count, price and sell. Give it what the buyer would type ("cleaning companies in Texas", "denver plumbers formed last 30 days with a phone", "NAICS 238220", "SIC 1711", "MCC 5812", "google category plumber") and you get back a list shape in the one filter contract — `states`, `filters`, `sort`, `lane`, `cap` — with a one-sentence `readback` to show the buyer, `assumed` (every default and substitution, named), `unresolved` (the words it could not place) and up to three `alternatives`. It is the same interpreter behind the buy page's search box, so a person and an agent get the same list from the same words. It never answers in prose, never asks a question back, never looks a person up, and never emits a predicate on a masked field (`contact_name`, `email_primary`, `phone_primary`). Every classification system is an entry point — a seller who thinks in MCC, SIC, NAICS or Google category gets the same list. A code we do not carry directly WIDENS to its parent group or the industries the crosswalk ties it to, and `assumed` names the step; to see the other systems' equivalents for a code, call `explain_concept`. When the buyer asked a question or raised an objection instead ("where does this come from", "is it legal to call", "how fresh"), the response also carries `answer` (`{family, headline, body, next_step, facts}`) — our answer, in our words, written to be shown to the buyer as is. When the ask pulls two ways — the newest records AND a phone to call — `alternatives` come back live-quoted (`quote: {records, total_cents, unit_cents}`, a `why`, one `recommended`): call today · mail first with phones verified on order · a standing order. Orders are per record with no minimums, so a small first order works. The returned shape is the input `quote_list` takes for the count and the price, and `checkout_list` takes to buy it. Args: text: What the buyer typed, in their own words. state: Optional two-letter state hint (live states: CO, CT, FL, NY, OR, TX, VA). current: Optional current shape `{states, filters, lane, cap}` — the answer merges into it instead of starting over. Returns: `{states, filters, sort, lane, cap, readback, assumed, unresolved, alternatives, used_model}` — always a shape, never a 500.

The filter contract, from the schema endpoint (`GET /api/v1/schema/attributes?include=grammar`): fields, grammar, or recipes. Call this before building `browse_leads` filters you haven't used before. Each field lists the `allowed_values` when its vocabulary is closed and its `accepted_words` — the buyer's own words that mean a stored value ("cell" → mobile, "CST" → the Central zones) — so you never have to learn our spellings; typed values are understood anyway. Args: section: `fields` (default) — every one of the 85 filterable fields as `{"field", "label", "type", "operators", "sortable", "masked", "allowed_values"?, "description", "job", "absence", "synonyms"}`: `operators` is the ENFORCED set for that field (its type's row, or a narrower pseudo-field override), `sortable` flags the 76 fields `sort` accepts, `masked` flags `contact_name`, `email_primary`, `phone_primary` (redacted for keyless callers, who may not filter the summary on them), `allowed_values` lists the vocabulary where it is enumerable (tiers in rank order, canonical `status` / `entity_type` values — identical across all states), `job` names the jobs-ladder step the field serves (LINK / CHOOSE / REACH, or IDENTITY), `absence` states what a zero/null means per state where states differ, and `synonyms` lists the buyer words that name this field; canonical-vocabulary fields additionally carry `"canonical": true`, the `"values"` list and a `"raw_variant"` naming the sibling field that filters the raw state-specific SOS codes. `grammar` — the leaf and group shapes (`and` / `or` / `not`), the operator row per field type and the pseudo-field overrides, the null semantics of the negative operators, and the sort contract (multi-key shape, rank-ordered tier fields, tiebreaker) — plus `sortable_fields` and `masked_fields` projected from the same response. 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. `recipes` — the outcome-recipe bank (`GET /api/v1/schema/recipes`): jobs-to-be-done answered with the exact filters, what each score means for that job, and the load-bearing caveats. The same payload backs the Browse UI's filter builder, so anything listed here works on browse, summary, export, checkout and pipeline scoping alike.

Where we are live right now — the state codes, read from production, never a cached page. Call it before promising a buyer a state: a state not in this list is not live yet. Returns `[{"state": "CO"}, ...]` — codes only, no counts. For how many records a state holds, `quote_list` (or `browse_leads(summary=True)`) on that state returns the live graded counts.

The shelf — ready-made business type × state lists, with live counts. Returns the same live document `list_starters` returns — `{"count": N, "starters": [...]}`, one entry per (state, business type) with its display `label`, the exact `filters` it opens with, the graded counts (`matching`, `sellable`, `verified_one`, `verified_both`) and `price_from_cents` (the name-and-address grade — the floor, not a flat price) — plus a `note`. The shelf is the starter lists: every count here is live, the price is quoted per record by `quote_list`, and the payment link comes from `checkout_list`. Every purchase is one-time; a buyer who wants new filings to keep coming sets up a standing order from a paid order's receipt, paid up front for the run. There are no fixed-price products and nothing here carries a `product_id`: pass a starter's `filters` to `quote_list` for the exact count and price, then to `checkout_list` for the link. 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). Only sellable records (the filing names a person) are ever billed, and the selected records are frozen when the link is minted, so what is billed is what is delivered. Evaluate before buying: `browse_leads` with the same `filters` shows real masked records for free.

Ready-made lists to start from: every live state × business type, with live counts and a starting price. Returns one document: `{"count": N, "starters": [...]}` — one entry per (state, business type): the display `label`, the exact `filters` the card opens with, the graded counts (`matching`, `sellable`, `verified_one`, `verified_both`) and `price_from_cents` (the name-and-address grade — the floor, not a flat price; the full price ladder comes from `quote_list`). Show these to a buyer who has not said what they want yet, then narrow with `interpret_list` or your own filters and price the result with `quote_list`. Counts come from live inventory, cached server-side for a few hours — never a stale copy from a marketing page.

What this list costs before anyone pays: how many records name a person, and the price by grade. Pass a saved list (`list_id`, the 8-char id in `#browse?list=<id>`) or an inline shape (`filters` + `states`; omit `states` for every live state: CO, CT, FL, NY, OR, TX, VA). You get the same numbers the buy page shows a person: `matching`, `sellable`, `verified_one`, `verified_both`, `no_channel`, `unnamed`, `facets`, `prices` (the live graded price rule + `price_rule_version`), `quote` (present when `lane` or `cap` is given), `exact`, `computed_at`, `quote_valid_until` (counts refresh tomorrow morning; the quote holds until then), `per_state`, and the `_meta` provenance block every read carries (schema_version, freshness, source, access_level). When a count is zero by design the payload adds `zero_reasons` — a state that never publishes the value, or a channel asked of records too new to carry one yet: the morning after the state posts a filing the record carries the name and mailing address; phone and email are verified when you order. Each reason names the widened count (`nearest_alternative`, e.g. "last 90 days: 99 with a phone") and the filters that reach it (`alternative_filters`), so a zero is never silent. **Values are understood, not matched literally.** 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. **Billing discipline — read before quoting money to anyone.** Only `sellable` records — matching records whose filing names a person — are ever billed or delivered. `matching` includes `unnamed` records with no person to reach; it is never a billable count and must never be presented as one. Every price line is computed from `sellable` and its grades: 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 grade; `best` = each record at its own grade, verified first; `contact` = only records with a verified phone or email — add a `has_email` filter for emailable now, `has_phone` for callable now). Cap: `{"type": "count|budget", "value"}` — records for count, cents for budget. Quote the server's numbers, never arithmetic of your own. Each `quote.lines[]` entry carries `ships` (what a record at that grade ships with, in the buyer's words — a name-and-address record never ships a phone or email), and the summary carries `forecast` ({checked, phone_expected, email_expected, both_expected, basis, as_of}): how many of the records still to find on would come back with a verified phone or email, from our measured outcomes on comparable records, stated with its basis. `ceiling_cents` is the most a buyer can be charged: today's total plus the forecast upgrades, charged only for what we find. Every record ships the owner's name and mailing address plus the business facts — the business name, entity type and status, the state filing number and formation date, the industry with its NAICS, SIC and Google Business codes, the registered agent, the Lead Reference, and the Reachability, Contact Relevance and Contact Confidence scores; before paying, see one whole sample record (invented, every field real): https://app.goodleads.club/lead/GL-CO-900000, and open the exact file (11 made-up records, every column): https://app.goodleads.club/api/v1/commerce/sample-file?format=xlsx (or format=csv). A quote supports three choices — callable now (a verified phone), emailable now (a verified email, verified for deliverability and recent activity), or newest, mail-first — plus a standing order. Orders are per record with no minimums, so a small first order works. `checkout_list` takes the same list / shape, lane and cap to buy exactly what was quoted. **Offer codes.** If your human was given an offer code — a price we agreed with them, like `GL-7K3Q9M` — pass it as `offer_code` here AND on `checkout_list`, so the quote and the payment link carry the same price. A code is a ceiling: every grade bills at the lower of list and the offer, never above list, and the reply adds an `offer` block (what is left on it, when it expires). A code that cannot be used answers with the reason in plain words; quoting again without the code gives list price. Args: list_id: A saved list id. Mutually exclusive with `states` / `filters`. states: State codes for an inline shape; omit for every live state. filters: Filter clauses in the one contract (see `list_filterable_fields`). include_held: Include inactive-or-holding entities (default False). include_existing: Include existing businesses with a new filing (a registration, a conversion, a reinstatement, a move, a rename) — the default quotes Just started only, exactly as Browse and the file do. Naming `filing_kind` / `business_origin` in `filters` widens on its own. lane: `all` / `best` / `contact` — asks for a `quote`. cap: `{"type": "count|budget", "value": <int>}` — the dial the quote is solved against. offer_code: The offer code your human was given, if any. 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. Inline shapes only. Returns: The summary contract described above. Keyless callers may not filter on `contact_name`, `email_primary`, `phone_primary` (422).