Lyre Leads API

Integrate AI-powered Google Maps lead generation directly into your applications, AI agents, LangChain pipelines, and automation workflows. Search businesses, retrieve 40+ company-level data points per lead — including verified emails, AI-discovered contacts with personal LinkedIn profiles, and 280+ tech stack detections — and score them with AI. All via a simple REST API.

✓ REST API ✓ OpenAPI 3.0 ✓ LangChain / AI Agent Ready

ℹ️ API access is available on Growth plans and higher. Generate your API key in Account → API Keys.

Quick Start

Get your first API call working in under 2 minutes.

Get an API Key

Check Your Balance

Call GET /api/v1/balance with your Bearer key to confirm it works.

Search for Leads

Call POST /api/v1/search with query, city, and country.

Score with AI

Pass result IDs to POST /api/v1/evaluate with your AI model ID.

First API call

cURL

curl https://lyreleads.com/api/v1/balance \
  -H "Authorization: Bearer lyre_your_api_key_here"

Python

import requests

API_KEY = "lyre_your_api_key_here"
BASE_URL = "https://lyreleads.com"
headers = {"Authorization": f"Bearer {API_KEY}"}

resp = requests.get(f"{BASE_URL}/api/v1/balance", headers=headers)
print(resp.json())
# {'tier': 'Growth', 'tokens_balance': 4500, 'tokens_monthly_allocation': 5000, ...}

Node.js

const res = await fetch('https://lyreleads.com/api/v1/balance', {
  headers: { 'Authorization': 'Bearer lyre_your_api_key_here' }
});
const data = await res.json();
console.log(data.tokens_balance); // 4500

Authentication

All API v1 requests require an API key sent as a Bearer token in the Authorization header:

HTTP Header

Authorization: Bearer lyre_<your-64-hex-key>

API keys are scoped to your account. They inherit your token balance and tier permissions. You can create up to 10 active keys per account and revoke them at any time from the Account page.

⚠️ Your API key is shown only once at creation. Store it securely in environment variables or a secrets manager — never hard-code it in your application source.

ℹ️ API access requires a Growth plan or higher. Free accounts cannot create API keys.

Error Handling

The API uses standard HTTP status codes. All error responses are JSON with an error field:

Status	Meaning	Common cause
200	OK	Request succeeded
400	Bad Request	Missing required field or invalid parameter
401	Unauthorized	Missing, invalid, or revoked API key
402	Payment Required	Insufficient tokens — buy more or wait for monthly reset
403	Forbidden	Plan upgrade required, or account suspended
404	Not Found	Resource not found (model, result)
429	Too Many Requests	Rate limit exceeded (120 req/min per key)
500	Server Error	Something went wrong on our end

Error response example

{
  "error": "Insufficient tokens.",
  "tokens_needed": 20,
  "tokens_balance": 5,
  "upgrade_url": "/pricing"
}

Rate Limits

The API allows 120 requests per minute per API key. Exceeding this returns a 429 response. The limit resets every 60 seconds.

Each search result or AI evaluation costs 1 token. Check your balance at any time via GET /api/v1/balance.

Endpoints

Token Balance

GET /api/v1/balance Returns your current token balance and plan info

No request body required.

Response

JSON

{
  "tier": "Growth",
  "tokens_balance": 4500,
  "tokens_monthly_allocation": 5000,
  "tokens_reset_date": "2026-02-01T00:00:00.000Z",
  "tokens_next_reset": "2026-03-01T00:00:00.000Z"
}

Search for Leads

POST /api/v1/search Search Google Maps for businesses. Each result costs 1 token.

Request Body

Parameter	Type	Description
queryrequired	`string`	Business type or keyword (e.g. "plumbers")
cityrequired	`string`	City to search in (e.g. "Berlin"). For disambiguation, include the region: "London, England" or "Springfield, Illinois"
countryrequired	`string`	Country name (e.g. "Germany")
pagesoptional	`integer 1–5`	Pages of results (20 results/page). Default: 1

Request example

{
  "query": "plumbers",
  "city": "Berlin",
  "country": "Germany",
  "pages": 2
}

Response

{
  "results": [
    {
      "name": "Müller Plumbing GmbH",
      "address": "Hauptstraße 42, 10115 Berlin",
      "phone": "+49 30 12345678",
      "website": "https://mueller-plumbing.de",
      "rating": 4.7,
      "review_count": 183,
      "type": "Plumber"
    }
  ],
  "results_count": 40,
  "tokens_used": 40,
  "tokens_remaining": 4460,
  "query": "plumbers",
  "city": "Berlin",
  "country": "Germany"
}

Python example

Python

resp = requests.post(
    f"{BASE_URL}/api/v1/search",
    headers=headers,
    json={
        "query": "plumbers",
        "city": "Berlin",
        "country": "Germany",
        "pages": 2
    }
)
data = resp.json()
for biz in data["results"]:
    print(biz["name"], biz.get("website", "—"))

Retrieve Past Results

GET /api/v1/results Paginated access to your stored search results

Query param	Type	Description
limitoptional	`integer`	Results per page (default 20, max 100)
offsetoptional	`integer`	Pagination offset (default 0)
queryoptional	`string`	Filter by search query (partial match)
search_idoptional	`integer`	Filter by search history ID

cURL

curl "https://lyreleads.com/api/v1/results?limit=50&query=plumbers" \
  -H "Authorization: Bearer lyre_..."

Response

{
  "results": [ /* array of result objects */ ],
  "total": 2540,
  "limit": 50,
  "offset": 0,
  "has_more": true
}

Each result object contains enrichment data including email, facebook_url, instagram_url, linkedin_url, has_facebook_pixel, has_google_analytics, cms_platform, tech_stack (JSON array of all 200+ detected technologies), plus categorized tech columns: tech_frameworks, tech_analytics, tech_advertising, tech_marketing, tech_ecommerce, tech_customer_tools, tech_infrastructure. Boolean signals: has_ad_pixels, has_marketing_automation, has_ecommerce, has_cookie_consent, has_reviews_widget, has_heatmaps, has_scheduling. Also includes chat_widget, booking_system, crm_platform, is_mobile_friendly, has_ssl, contact_name, contact_title, contact_linkedin, contact_profile_url, ai_rating, and ai_notes.

AI Lead Scoring

POST /api/v1/evaluate Score leads with your AI model. Each result costs 1 token.

Parameter	Type	Description
model_idrequired	`integer`	ID of your AI model (from GET /api/v1/models)
result_idsrequired	`integer[]`	Array of result IDs to score (max 200)

Request + response

// Request
{
  "model_id": 42,
  "result_ids": [1001, 1002, 1003]
}

// Response — evaluation starts async
{
  "success": true,
  "job_id": "a1b2c3d4",
  "status": "started",
  "total_results": 3,
  "model_name": "My Plumber Qualifier",
  "poll_url": "/api/jobs/a1b2c3d4/status"
}

Poll poll_url to get live progress. AI scores (0–10) and explanations are saved to each result and retrievable via GET /api/v1/results once complete.

List AI Models

GET /api/v1/models Returns your saved AI scoring models

Response

{
  "models": [
    {
      "id": 42,
      "name": "My Plumber Qualifier",
      "description": "Scores plumbers in Berlin for HVAC upsell potential",
      "created_at": "2026-02-01T12:00:00.000Z"
    }
  ]
}

OpenAPI Spec

GET /api/v1/openapi.json OpenAPI 3.0 specification — no auth required

Returns a complete OpenAPI 3.0 spec. Use this to auto-configure LLM tool-use, Postman, Swagger UI, or any OpenAPI-compatible tooling. No API key required to fetch the spec.

LangChain example

from langchain.tools import OpenAPISpec, APIOperation
from langchain.chains import OpenAPIEndpointChain

spec = OpenAPISpec.from_url("https://lyreleads.com/api/v1/openapi.json")
# Agent can now auto-discover and call Lyre Leads endpoints