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"}…

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…

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,…

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…

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` expla…

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`, `registered_agent_name`). 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 p…

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 86 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 77 fields `sort` accepts, `masked` flags `contact_name`, `email_primary`, `phone_primary`, `registered_agent_name` (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…

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 —…