Use case · AI agents (Claude Code, Cursor, Codex)

Local business leads your AI agent can fetch on its own

Developers and operators who already work inside an AI coding agent and want prospect lists without leaving it.

How it is usually done today

• Asking the agent to browse Google Maps directly, one listing at a time.
• Wiring a raw scraping actor, then a separate email finder, then a verifier.
• Copy-pasting CSVs from a lead tool UI into the agent for cleanup.

Why that hurts

• Browsing agents are slow, get blocked, and miss listings.
• Gluing three vendors together means three keys, three bills and three data shapes the agent has to reconcile.
• A raw Maps scrape has no owner name, no email status and no phone line type — the agent still has to go find them.

How LeadMerlin does it

1. 1

   Paste the skill

   Copy the LeadMerlin skill from the docs into your agent (a Claude Code skill, a Cursor rule, or AGENTS.md for Codex).

2. 2

   Set your key

   Export LEADMERLIN_API_KEY in your shell. The skill tells the agent to read it from the environment, never to write it into files.

3. 3

   Ask in plain English

   The agent resolves the city with /v2/locations, sharpens a vague niche with /v2/suggest, starts a search job, polls it, and pages through results.

4. 4

   Export

   The agent writes a CSV with a fixed header order, ready for GoHighLevel, Instantly, HubSpot or Airtable.

What the agent runs under the hood

curl "https://api.leadmerlin.com/api/v2/locations?q=austin" \
  -H "x-api-key: $LEADMERLIN_API_KEY"

curl -X POST "https://api.leadmerlin.com/api/v2/searches" \
  -H "x-api-key: $LEADMERLIN_API_KEY" \
  -H "content-type: application/json" \
  -d '{"keyword":"roofing contractor","location_codes":[1026201],"strictness":"moderate"}'

curl "https://api.leadmerlin.com/api/v2/jobs/$JOB_ID" \
  -H "x-api-key: $LEADMERLIN_API_KEY"

curl "https://api.leadmerlin.com/api/v2/jobs/$JOB_ID/results?limit=200" \
  -H "x-api-key: $LEADMERLIN_API_KEY"

Location codes in these examples are placeholders — always look yours up with GET /v2/locations first.

What comes back

Most useful for this job:

• Structured JSON with consistent field names, so the agent does not have to guess.
• Best email and phone promoted to the top level, full lists under contact.all_emails[] and contact.all_phones[].
• Job status includes category_facets and off_niche_count so the agent can explain what it filtered.

Limits and honest caveats

• Search jobs are asynchronous. Enrichment typically takes a minute or more, so the agent has to poll.
• Owner names only appear when the business website states them — not every lead will have one.
• Your agent needs network access and permission to run HTTP requests.

Pricing

• 1 lead credit per business that has a website to enrich.
• Listings without a website are never charged (counted as skipped, not returned in results).
• Off-niche listings removed by the niche filter are never charged.
• Failed enrichments are refunded automatically.
• A search charges only what your balance covers: with 40 credits left, it enriches the 40 top-ranked matches. Set max_leads to cap any search.
• Locations, niche suggestions, polling and demo endpoints are free.
• Phone line-type lookups have a monthly allowance: 100 on the free start, 1,000 Starter, 2,000 Pro, 4,000 Agency. Numbers looked up before are free. Past the allowance, phones still come back without a line type.

FAQ

Related