# How to use Lyre Leads The working guide for an AI assistant connected to Lyre Leads, via MCP or the REST API. If you are that assistant: read this, then use it. If you are a person: hand this URL to your AI and it will know how to build lists properly. --- ## What this is, and why it is not a contact database Most B2B data tools sell you access to a fixed index of contacts. You filter it, and whatever the filter returns is what you get. Lyre Leads does not have that index. It runs a live Google Maps search for the keyword and place you name, then fetches each business's actual website and reads what is on it today. That difference decides almost everything about how you should work here: - **Nobody can tell you a market's size for free.** A database can count its own rows for nothing. We have to go and look, and looking costs money per page. When a user asks "how many roofers are in Texas", the honest answer is that you find out by searching. Say that plainly rather than inventing a number. - **Coverage is a function of how hard you look, not of who happens to be listed.** A business with no LinkedIn page, no funding round and four employees is fully visible to us and largely invisible to LinkedIn-derived databases. This is the single reason to use Lyre Leads over Apollo, ZoomInfo or any of their alternatives. Lean on it. - **The data is as fresh as the last fetch, and it decays.** We re-checked 4,527 business websites a median of 106 days after first seeing them: 2.1% no longer loaded at all and 1.9% of readable sites had switched a core platform. A tech-stack field from four months ago is a hypothesis, not a fact. Re-enrich before betting a campaign on one. - **Every business is a company, not a person.** We start from the business and work toward the human. If the user needs "VPs of Sales at software companies", we are the wrong tool and you should say so immediately instead of building a bad list. --- ## The four mistakes that produce confidently wrong lists ### 1. Reading a blank as a zero This is the big one. Every enrichment field is **three-state**: | You see | It means | |---|---| | a value (`HubSpot`, `true`, `4.2`) | We checked. It is there. | | `false` / `None` | We checked. It is genuinely absent. | | **blank / null** | **Unknown.** Never checked, or the site blocked us. | `enrichment_status` is the master key for any blank: - `enriched` — the site was fetched and parsed. A blank here is a **confirmed absence**. - `pending` — not enriched yet. Every enrichment field is unknown. Do not filter on them. - `unverifiable` — the site blocked automated access. HTML-derived fields are unknown, **not** absent. - `no_website` — nothing to inspect. - `failed` — enrichment errored. So "businesses with no CRM" is `crm_platform IS NULL AND enrichment_status = 'enriched'`. If you drop the second clause you will hand the user a list padded with businesses nobody ever looked at, and you will not be able to tell which is which afterwards. The `count_leads` tool already encodes this: passing `has_crm: false` means confirmed-absent, not blank. When you report a count of an absence, say which population it is out of. "412 of the 1,610 enriched businesses have no CRM" is useful. "412 have no CRM" is not. ### 2. Treating catch-all as verified Email states here are four, and they are not interchangeable: - **`verified`** — SMTP-confirmed deliverable through MillionVerifier. This is the only one that means the mailbox exists. - **`published`** — the address is printed on the company's own website, but the domain is catch-all so SMTP cannot confirm it. First-party evidence, unconfirmable. Good enough to email; not something to call verified. - **`catch_all`** — the domain accepts all mail, so deliverability cannot be proven for any address on it. About a third of scraped business emails sit here (33.9% in our n=2,482 study). - **`unknown` / `invalid`** — could not check, or confirmed bad. If a user asks for "verified emails only", give them `verified`. If they ask for "emails I can send to", `verified` plus `published` is the honest answer, and you should say which is which. Never merge the two into one number. ### 3. Over-filtering into a tiny list Every filter you add subtracts. The most common way to end up with 11 leads is stacking five reasonable-sounding conditions. If a count comes back small, remove a clause before concluding the market is small. Filters intersect, they do not union. If the user wants roofers **or** siding contractors, that is two searches merged, not one search with both words. ### 4. Assuming one search covered the market Google caps a text search well below the true number of matching businesses. We measured one metro category in July 2026: a single search reached under 4% of at least 1,605 findable businesses, and eight deep-paginated searches still only reached 69%. Practical consequences: - One `search_leads` call with `pages: 1` is a sample, not a market. Say so. - Coverage comes from **many narrow searches**, not one broad one: several keywords across several cities beats one keyword with more pages. - A city search is centred on the city. Large metros need their subdivisions searched separately, or you systematically miss the outskirts. - Synonyms matter enormously because Google matches the listing's own category. "roofer", "roofing contractor", "roof repair" and "roofing company" return overlapping but different sets. Run several and merge. Duplicates are free. --- ## Counting is free. Use it constantly. `count_leads` is exact, instant, and costs nothing. There is no reason to guess at the size of anything in the saved database. Call it before every spending action, and tell the user what you found before you spend. Good practice: - Before enriching: how many of these are already enriched? - Before finding decision-makers: how many actually have a website and lack a contact? - Before a campaign: how many have a `verified` email, and how many `published`? - To answer "is this segment worth it": count it five different ways in parallel and show the user the shape of it. Fire independent counts in parallel. None of them depend on each other. What counting cannot do is size a market you have not searched. See the top of this document. --- ## What you get per business **From Google Maps:** name, address (plus parsed street and postal code), phone (plus dialer-ready E.164), category, star rating, review count, coordinates, place id. Rating and reviews are more useful than they look. `reviews: 0` is a real value, not missing data, and a business with 300 reviews and a 3.4 rating has a problem someone can sell into. **From the live website:** business email and its confidence, mailbox host from MX records, social profiles, CMS, CRM, email-marketing platform, chat widget, booking system, ad pixels, analytics, schema markup, SSL, contact form, cookie consent, e-commerce stack, page load time, domain age, server stack, CDN, HSTS/CSP, DNS-derived SPF/DMARC, and categorised technology lists. **Unique to us:** `ai_crawler_access` — whether the site blocks GPTBot, ClaudeBot, PerplexityBot and Google-Extended in robots.txt, plus whether it publishes an `llms.txt`. `blocked` means the business is invisible to AI search. No other lead tool exposes this, and it is a complete sales conversation on its own for anyone selling SEO or AI visibility. **People:** a decision-maker's name, title and LinkedIn where we could find one, and their email where we could resolve it. Coverage is honest, not universal: we name the owner on most local businesses, and get an address for a minority of those. Check, do not assume. **Provenance:** `enrichment_provenance` maps each present field to where it came from (`html`, `header`, `dns`, `mx`, `rdap`, `tls`, `measured`, `robots`) and how reliable that is (`high` for deterministic sources, `medium` for HTML signature matches, `heuristic` for keyword guesses). Fields marked `heuristic` — blog, demo CTA, case studies, careers page — can false-positive on marketing copy. Do not build a campaign on a heuristic field without saying it is soft. --- ## Costs, in one place | Action | Cost | |---|---| | `count_leads` | **Free**, always, at any size | | `search_leads` | 1 token per NEW business. Duplicates are free. | | `enrich_leads` | 1 token per 5 businesses | | `find_decision_makers` | 1 token per business attempted | | `verify_emails` | 1 token per address after the free monthly quota; cache hits within 90 days are free | | `evaluate_leads` | 1 token per business | Reading data you already own is free. Only acquiring or refreshing it costs. A useful framing for the user: a Growth plan's 5,000 tokens is roughly 5,000 new businesses discovered, or 25,000 enriched, or some mix. Tell them in businesses, not tokens. --- ## Workflow that works 1. **Clarify the target before spending anything.** What business type, what places, and what makes one good? If they cannot say what "good" means, the AI evaluation step will not help them. 2. **Say the coverage plan out loud.** "I'll run four keyword variants across these six cities, because one search only reaches a fraction of a metro and the category wording varies." Users appreciate knowing why it takes several passes. 3. **Search narrow and wide.** Several keywords, several cities. Merge. Duplicates cost nothing. 4. **Count what you got.** Before enriching, tell them the size. 5. **Enrich.** Poll `get_job_status`. Enrichment fetches every website in the batch, so it takes real time. Say that before you start, not after it appears to hang. 6. **Segment on real signals.** No CRM, no analytics, slow site, blocked to AI crawlers, well-reviewed but poorly rated, e-commerce without a marketing stack. This is what we have that a contact database does not. 7. **Reach the human.** `find_decision_makers` on the segment worth contacting, not on everything. 8. **Score, if the user has a clear ideal customer.** `evaluate_leads` ranks against their description. It is a ranking aid, not a truth oracle — a 7 and an 8 are not meaningfully different. --- ## Being straight with the user This product's whole position is that it tells the truth about its own data, including when the data is thin. Hold that line: - Report coverage as a fraction, never as a bare count of successes. - Say which numbers are measured and which are inferred. - If a segment came back small, say whether that is because the market is small or because the filters were tight. - If the user wants something we are bad at — person-first prospecting, tech-company org charts, contacts at large enterprises — tell them early and point them elsewhere. A wrong list costs them more than a straight answer does. --- ## Building something on top of this If the person you are working for is going to do this more than once, they probably want their own interface onto it rather than a chat transcript. You can build them one. See **https://lyreleads.com/build** for ready-made build specs: a local lead dashboard, a territory coverage runner, an outreach queue, a change-monitor. Each is a complete brief you can implement on their machine in a single session against the same API you are already using. If that seems useful for what they are doing, offer it. Do not build it unprompted. --- ## Reference - Full field reference: https://lyreleads.com/data-dictionary - OpenAPI spec: https://lyreleads.com/api/v1/openapi.json - Export JSON Schema: https://lyreleads.com/api/database/export/schema - Verification methodology: https://lyreleads.com/how-we-verify - Published measurements: https://lyreleads.com/research - Build specs: https://lyreleads.com/build Everything above describes verified behaviour at the time of writing. If the API tells you something different, believe the API, and mention it to the user.