API Documentation

Connect Live Lead Extractor to your own software. For developers and automation tools — no coding knowledge needed to read this page.

What is this?

The Live Lead Extractor API lets a program do everything the website does: run a lead search, watch its progress, and download the results — automatically, with no one clicking around in a browser. If you (or your developer, or an automation tool) want fresh leads flowing into your own system on a schedule, this is the page that explains how.

If you just want leads in your CRM or Google Sheets without writing any code, you don't need the API — use our Zapier integration instead (you'll find it on your Account tab once your plan includes integrations).

New to APIs? Think of it as a service window: your software slides a written request through (for example, "25 roofers in Tampa"), and we slide back a neatly organized list. The "API key" below is the ID badge that proves the request is really from your account.

Getting your API key

Everything on this page — the AI assistants below and the developer API further down — is unlocked by an API key: a long secret code that identifies your account.

1. Log in and open the Account tab.
2. Find the API keys section — the full REST API is included with every plan that includes integrations: Growth, Agency, and Scale.
3. Type a name for the key and click Create key. Name it after the tool it's for — claude, chatgpt, zapier, my-crm-sync.
4. Click Copy — and if you ever need it again, every key in your list has a Copy button.

Connecting more than one tool? Create one key per tool. Any key works anywhere, but giving each tool its own key means you can revoke one (and disconnect just that tool) without breaking the others, and the "last used" date tells you which tool is which.

Treat every key like a password. Anyone who has one can run searches and spend credits on your account.

Use it inside Claude or ChatGPT (no code)

You can also use Live Lead Extractor by just talking to your AI assistant — "find 25 roofers in Tampa with emails" — and letting it run the searches for you. This works through MCP, a standard that lets AI chat apps connect to outside services. One-time setup, no programming.

Each app connects with its own address: an API key added to the end of this URL. Connecting both Claude and ChatGPT? Create a key for each (named claude and chatgpt) and build one address per app:

https://liveleadextractor.onrender.com/mcp/YOUR_API_KEY

Because the key is part of the address, treat the whole URL like a password — don't share it or post screenshots of it.

Connect it in Claude:

1. In Claude (web or desktop), open Settings → Connectors.
2. Click Add custom connector.
3. Name it Live Lead Extractor, paste your connection URL, and click Add.
4. Claude checks the connection and lists the available tools — you're done.

Connect it in ChatGPT:

1. In ChatGPT (on the website, not the phone app), open Settings and look for Apps — on some accounts the same section is called Plugins or Apps & Connectors.
2. Inside it, find and turn on Developer mode (it may sit at the bottom of the section, or under Advanced settings). The create option stays hidden until you do.
3. Go back to the section and click Create app (or Add). Name it Live Lead Extractor, choose Server URL as the connection type, and paste your connection URL.
4. Set authentication to No auth — your key is already in the URL.
5. Click Create, then Connect. In a new chat, type @ and pick Live Lead Extractor.

Try it with a small prompt first:

Find 10 plumbers in Tampa, FL with at least 4 stars. Check my Live Lead Extractor account first.

The assistant will check your credits, start the search, wait for it to finish, and show you the results — searches spend credits from your normal balance, same as the website, and every search also appears in your Search History. You can then say "now enrich them" to run real AI enrichment (owner names and best emails, saved to your account), or ask it to write an email intro for any lead. If the connection fails, re-check the URL for extra spaces and make sure the key wasn't revoked; if searches won't start, the error message will say why (usually credits or plan reach).

The basics

All requests go to this base address, over HTTPS:

https://liveleadextractor.onrender.com

Send your API key with every request, in an X-API-Key header:

curl -H "X-API-Key: llx_your_key_here" \
  https://liveleadextractor.onrender.com/me

If your tool can't set headers, you can also pass the key in the address as ?api_key=llx_your_key_here — but prefer the header: keys in URLs can end up saved in logs and browser history.

Requests and responses use JSON. Credits work exactly like they do on the website: you are only charged for leads actually delivered — one credit per lead. Searches never spend more credits than you have.

Check your account and credits

GET /me

Returns your profile, plan, and live credit balance. This is also the quickest way to test that your key works.

curl -H "X-API-Key: llx_your_key_here" \
  https://liveleadextractor.onrender.com/me

Sample response (trimmed):

{
  "email": "you@example.com",
  "tier": "agency",
  "credits": 2450,
  "entitlements": { "api_access": true, "scope": "state" }
}

Start a search

POST /search/start

Kicks off a live search and returns immediately with a search_id. The search keeps running on our side — leads are scraped fresh from Google Maps and each business's own website, which takes time (a couple of minutes for a small city search; large state-wide searches can run 20–50 minutes).

curl -X POST https://liveleadextractor.onrender.com/search/start \
  -H "X-API-Key: llx_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "industry": "plumber",
    "location": "Tampa, FL",
    "requested_count": 25,
    "scope": "city"
  }'

Sample response:

{
  "search_id": "8f2b1c9e-…",
  "requested": 25,
  "status": "running",
  "poll": "/searches/8f2b1c9e-…"
}

Body fields:

Filters (all optional; leads that don't match are dropped before you're charged):

If the search can't start — not enough credits, or a location wider than your plan allows — you get a 400 response with a plain-English message explaining why.

Check progress

GET /searches/{search_id}

Poll this every 15–30 seconds until status is "done".

curl -H "X-API-Key: llx_your_key_here" \
  https://liveleadextractor.onrender.com/searches/8f2b1c9e-…

{
  "search_id": "8f2b1c9e-…",
  "industry": "plumber",
  "location": "Tampa, FL",
  "status": "done",
  "leads_found": 25,
  "emails_found": 19,
  "completed_at": "2026-07-21T18:04:11+00:00"
}

status is "running", "done", or "failed" (failed searches don't charge you for undelivered leads).

Get the results

GET /searches/{search_id}/leads

Returns every lead from the search as JSON — one object per business, with every email we found and confidence scores.

[
  {
    "lead_id": "c41d…",
    "business_name": "Bayshore Plumbing Co",
    "industry": "Plumber",
    "website": "https://bayshoreplumbing.com",
    "phone": "(813) 555-0147",
    "address": "402 W Kennedy Blvd, Tampa, FL",
    "rating": 4.8,
    "review_count": 132,
    "owner_name": "Maria Lopez",
    "owner_title": "Owner",
    "primary_email": "maria@bayshoreplumbing.com",
    "emails": [
      { "email": "maria@bayshoreplumbing.com", "type": "personal", "confidence": 0.95, "is_primary": true }
    ],
    "socials": { "facebook": "https://facebook.com/bayshoreplumbing" }
  }
]

List your search history

GET /searches

Your most recent 100 searches, newest first — the same list you see on the Search History tab. Re-fetching a finished search's results never costs credits.

Download as a spreadsheet

GET /searches/{search_id}/export — the full results as a CSV file (all fields).

GET /searches/{search_id}/campaign-export?channel=… — a CSV pre-shaped for one outreach channel:

curl -H "X-API-Key: llx_your_key_here" -o leads.csv \
  "https://liveleadextractor.onrender.com/searches/8f2b1c9e-…/export"

AI enrichment & email intros

The same AI features as the website, callable programmatically. Both spend your plan's monthly AI allowances (with credit packs or your own AI key as overflow, exactly like on the site).

POST /searches/{search_id}/enrich — run AI enrichment on a search's leads: it reads the website text we stored for each business and identifies the real owner and the best decision-maker email, then saves the improvements to your account (they show up in Search History and every export). Optional JSON body {"lead_ids": ["…"]} restricts it to specific leads; no body means every lead in the search, up to your remaining allowance.

curl -X POST -H "X-API-Key: llx_your_key_here" -H "Content-Type: application/json" \
  -d '{}' \
  "https://liveleadextractor.onrender.com/searches/8f2b1c9e-…/enrich"

POST /leads/{lead_id}/enrich — the same, for a single lead.

POST /leads/{lead_id}/intro — writes a 2–3 sentence personalized cold-email opening for one lead, grounded in the business's real website text and reviews. The text comes back in the response and is not stored — save it on your side.

{ "intro": "Hi Maria, 132 reviews at 4.8 stars is no accident…", "ai_intro_remaining": 4988 }

Advanced: live streaming

POST /search/start + polling is the recommended pattern. But if you want results the instant each lead is found, POST /search (same body) holds the connection open and streams Server-Sent Events: a search_started event, then one lead event per delivered lead, then search_done. Use this only if your tooling handles SSE comfortably.

Interactive reference

Prefer to poke at the API in your browser? The interactive reference lists every endpoint with a Try it out button — paste your key into the X-API-Key field and experiment (real requests spend real credits).

A complete example

Start a search, wait for it, fetch the leads — in Python:

import time, requests

BASE = "https://liveleadextractor.onrender.com"
HEADERS = {"X-API-Key": "llx_your_key_here"}

# 1. Start
r = requests.post(f"{BASE}/search/start", headers=HEADERS, json={
    "industry": "roofer",
    "location": "Orlando, FL",
    "requested_count": 25,
    "filters": {"has_email": True, "min_rating": 4.0},
})
r.raise_for_status()
search_id = r.json()["search_id"]

# 2. Poll until done
while True:
    s = requests.get(f"{BASE}/searches/{search_id}", headers=HEADERS).json()
    if s["status"] in ("done", "failed"):
        break
    time.sleep(20)

# 3. Fetch results
leads = requests.get(f"{BASE}/searches/{search_id}/leads", headers=HEADERS).json()
print(f"{len(leads)} leads, {sum(1 for l in leads if l['primary_email'])} with email")

Errors

Errors come back as JSON with a human-readable detail message:

Questions?

Email support@liveleadextractor.com — we're happy to help you get connected. If you'd rather not write code at all, the Zapier integration on your Account tab does the most common jobs (new leads → CRM, Sheets, Slack) with zero programming.