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

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.
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.
Search narrow and wide. Several keywords, several cities. Merge. Duplicates cost nothing.
Count what you got. Before enriching, tell them the size.
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.
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.
Reach the human. find_decision_makers on the segment worth contacting, not on everything.
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.

Lyre Leads · Home · Agent guide · Build specs · API docs · Data dictionary