GoodLeads

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" is the buyer's word for the records themselves — eve…

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. Hand the URL to your human; do not represent the purchase as complete until they confirm 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, 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 w…

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. Hand the URL to your human; do not represent the purchase as complete until they confirm payment. For new work, use the dedicated buying journey: `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, 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…

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), 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. 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. The all-states form evaluates the full book (~800k records, ~40s) — when you only need one state, pas…

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.

Map YOUR word for a concept to this surface's fields — ask before concluding absence. 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.

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). 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") 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`). 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. Relay it to the buyer verbatim. 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. The close is two questions: present your human the quoted choice, then hand over the payment link for the one chosen — per record, no minimums, so a small first order is the normal first step. Next: hand the shape to `quote_list` for the count and the price, then to `checkout_list` 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, TX, VA). current: Optional current shape `{states, filters, lane, cap}` — the answer merges into it instead of starting o…

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. Args: section: `fields` (default) — every one of the 77 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 71 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…

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, billed monthly for the records actually delivered. 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, 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`) — relay it instead of a silent $0. **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…