GoodLeads
Find new business owner contacts the morning the state posts a filing.
Community: Submitted by a user or imported; check the owner before granting accessOnlineNo sign-inGlobalFreeCan modify data
What it can do
What data it sees
Do you need an account
No: the server works without sign-in
Find new business owner contacts the morning the state posts a filing. Preview free, pay per record.
Server tool list (13)
Raw names from tools/list. Only developers need these.
| find_lead_by_glid | 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. |
| data_quality_scorecard | 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, pass |
| browse_leads | 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 ` |
| interpret_list | 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 ov |
| quote_list | 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 |
| list_starters | 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. |
| checkout_list | 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 we |
| list_filterable_fields | 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 t |
| explain_concept | 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. |
| list_live_states | 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. |
| describe_surface | What GoodLeads is — call this to explain or vet us; to price a list, start with interpret_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. |
| list_products | The pre-shaped shelf — ready-made business type × state lists. Each product is a ready-made list of newly formed businesses for one business type in one state (or across every live state). Returns `product_id`, `name`, `description`, `state` (null = all live states), `lead_count`, `price_cents`, `period` and `stripe_price_id`. `period`: `monthly` = a standing order billed each period; absent = a one-time purchase. `stripe_price_id` is Stripe's own id for that price (null until the catalog syncs) — informational, never something to pass back. Pricing everywhere follows the one graded rule — per record, by what the record carries (name + address; plus one verified phone or email; plus both, verified) — and only sellable records (the filing names a person) are ever billed. For a shape of your own, or to see live graded counts and the exact price before buying, prefer the buying journey: `list_starters` (the shelf with live counts) or `interpret_list` → `quote_list` → `checkout_list`. Evaluate before buying: `browse_leads` with the same vertical/state shows real masked records for free. To buy a shelf product as-is, pass its `product_id` to `create_checkout`. |
| create_checkout | Mint a hosted Stripe Checkout link — for a shelf product, or for a list you shaped. 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, prefer the dedicated buying journey: `interpret_list` (the buyer's words → a shape) → `quote_list` (graded counts + the price) → `checkout_list` (this link, for a list). This tool remains for shelf products (`product_id` from `list_products`, priced per list by the same graded rule) and keeps accepting a list for compatibility — the list path is the same code as `checkout_list`. Two things you can buy: * a shelf product — `product_id` from `list_products`. `period`: `monthly` = a standing order billed each period; absent = a one-time purchase. The reply says which: `billing` (`monthly` | `one_time`), `price_cents` and a `note` that reads "This link starts a monthly standing order at $X per period" when the product carries a period; or * 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 bot |