LeadGen.tools API

Introduction

The LeadGen.tools REST API lets you search for leads, crawl websites for contact information, monitor competitor ads, and query Google Places — all from simple HTTP GET requests.

Every request is authenticated with your API key and user ID. Operations consume credits from your account balance, and responses are automatically cached to save credits on repeated queries.

Quick Start

Make your first API call in seconds:

curl "https://leadgen.tools/v2/api/v1/search.php?api_key=YOUR_KEY&query=marketing+agency+new+york&se=google"

Authentication

Every API request requires your API key:

The API key is sent as a query string parameter on every request:

GET /api/v1/search.php?api_key=YOUR_KEY&query=...

Base URL

All API endpoints are accessed under:

https://leadgen.tools/v2/api/v1/

For example, the full URL for the Lead Search endpoint is:

https://leadgen.tools/v2/api/v1/search.php

Response Format

All responses are returned as JSON with the Content-Type: application/json; charset=utf-8 header.

Success Response

{
  "status": "success",
  "credits_used": 10,
  "data": {
    // endpoint-specific data
  }
}

Error Response

{
  "status": "error",
  "code": "error_code",
  "message": "Human-readable description of the error."
}

The credits_used field tells you how many credits were deducted for that request. A value of 0 means the response was served from cache or no billable results were returned.

Error Handling

Errors return an appropriate HTTP status code along with a JSON body containing a machine-readable code and a human-readable message.

Credit System

Each API operation costs credits, which are deducted from your account balance. The exact cost depends on the endpoint and the results returned.

Caching

Responses are automatically cached to reduce latency and save credits. If an identical request has been made recently, the cached response is returned instantly with credits_used: 0.

Rate Limits

There are currently no hard rate limits enforced per-minute. However, some endpoints involve upstream API calls (ScraperAPI, Google Places) that may take several seconds to complete. Recommendations:

• Keep concurrent requests reasonable (under 5 simultaneous).
• Use the caching system — avoid polling the same query repeatedly.
• The crawler endpoint can take up to 2 minutes for deep crawls (up to 15 pages). Set your HTTP client timeout accordingly.
• Ad Spy with crawl enrichment may take 30–60 seconds on first call (crawling up to 15 ad landing pages).

Lead Search

Search Google, Bing, Yahoo, or DuckDuckGo for leads. Returns page titles, links, descriptions, and any emails or phone numbers found in the search results. You can pass a raw dork query or a saved recipe code.

Parameters

Example Request

curl "https://leadgen.tools/v2/api/v1/search.php?\
api_key=YOUR_KEY&\
query=marketing+agency+new+york&\
se=google&\
page=0&\
results_per_page=10"

Example Response

{
  "status": "success",
  "credits_used": 10,
  "data": {
    "query": "marketing agency new york",
    "search_engine": "google",
    "page": 0,
    "results_count": 10,
    "results": [
      {
        "title": "Top Marketing Agency in NYC | Example Agency",
        "link": "https://www.exampleagency.com/",
        "description": "Award-winning digital marketing agency based in New York City...",
        "emails": ["hello@exampleagency.com"],
        "phones": ["(212) 555-0147"]
      },
      {
        "title": "Creative Digital Agency NYC",
        "link": "https://www.creativeagency.io/",
        "description": "We help brands grow with data-driven campaigns...",
        "emails": [],
        "phones": []
      }
    ]
  }
}

Credit Calculation

• More than 7 results returned → 10 credits (flat)
• 7 or fewer results → 1 credit per email found in the SERP (junk emails like example@wix.com are excluded)
• No results → 0 credits
• Cache hit → 0 credits

Website Crawler

Crawl a website to extract emails, phone numbers, social media links, and page metadata. Automatically follows internal links and crawls up to 15 pages for thorough data extraction.

Parameters

Example Request

curl "https://leadgen.tools/v2/api/v1/crawl.php?\
api_key=YOUR_KEY&\
domain=example.com"

Example Response

{
  "status": "success",
  "credits_used": 3,
  "data": {
    "domain": "https://example.com",
    "pages_crawled": 8,
    "metadata": {
      "title": "Example Company — Home",
      "description": "We provide enterprise solutions for...",
      "keywords": "enterprise, solutions, consulting",
      "image": "https://example.com/og-image.jpg"
    },
    "emails": [
      "contact@example.com",
      "sales@example.com",
      "hr@example.com"
    ],
    "all_emails": [
      "contact@example.com",
      "sales@example.com",
      "hr@example.com",
      "support@otherdomain.com"
    ],
    "phones": [
      "(555) 123-4567",
      "(555) 987-6543"
    ],
    "social_links": [
      "https://twitter.com/example",
      "https://www.linkedin.com/company/example",
      "https://www.facebook.com/example"
    ]
  }
}

Response Fields

Credit Calculation

• 1 credit per unique domain-matched email found
• Minimum 1 credit if any data (emails, phones, or social links) is returned
• No data found → 0 credits
• Cache hit → 0 credits

How the Crawler Works

1. Fetches the main page at the provided URL.
2. Extracts emails, phones, social links, and metadata from the HTML.
3. Discovers internal links on the page.
4. Crawls up to 14 additional internal pages (15 total max).
5. Merges and deduplicates all results.

Ad Spy

Search for Google and Bing ads, automatically accumulate historical results, and enrich each ad with contact data by crawling the landing page. Every search adds newly discovered ads to a permanent database, so repeated queries return both fresh ads (currently running) and historical ads (previously seen).

Parameters

Example Request

curl "https://leadgen.tools/v2/api/v1/ads.php?\
api_key=YOUR_KEY&\
query=marketing+agency&\
se=google&\
include_history=true"

Example Response

{
  "status": "success",
  "credits_used": 10,
  "data": {
    "query": "marketing agency",
    "search_engine": "google",
    "page": 0,
    "fresh_count": 5,
    "historical_count": 3,
    "results_count": 8,
    "results": [
      {
        "position": 1,
        "title": "Best Marketing Agency | Award-Winning",
        "url": "https://www.exampleagency.com/",
        "ad_text": "Full-service digital marketing agency. Get a free audit today...",
        "search_engine": "google",
        "first_seen": "2025-01-15 10:00:00",
        "last_seen": "2026-02-15 14:30:00",
        "is_active": true,
        "contact_data": {
          "emails": ["info@exampleagency.com"],
          "phones": ["(555) 123-4567"],
          "social_links": [
            "https://facebook.com/exampleagency",
            "https://linkedin.com/company/exampleagency"
          ],
          "metadata": {
            "title": "Example Agency — Digital Marketing",
            "description": "Award-winning agency specializing in SEO, PPC, and social media.",
            "keywords": "marketing, agency, SEO, PPC",
            "image": "https://www.exampleagency.com/og-image.png"
          }
        }
      },
      {
        "position": 3,
        "title": "Grow Your Business | Old Ad Agency",
        "url": "https://www.oldagency.com/",
        "ad_text": "We help businesses scale with proven strategies...",
        "search_engine": "google",
        "first_seen": "2024-11-02 08:15:00",
        "last_seen": "2025-12-20 11:00:00",
        "is_active": false,
        "contact_data": {
          "emails": ["hello@oldagency.com"],
          "phones": [],
          "social_links": ["https://twitter.com/oldagency"],
          "metadata": {
            "title": "Old Agency",
            "description": "",
            "keywords": "",
            "image": ""
          }
        }
      }
    ]
  }
}

Response Fields

How It Works

1. Fresh search — Performs a live Google/Bing search to find currently running ads.
2. Store — Each fresh ad is saved to a permanent database. New ads are inserted; existing ads have their last_seen timestamp updated.
3. Load history — All previously stored ads for the same query are loaded and merged.
4. Crawl enrichment — Each ad's landing page URL is crawled to extract emails, phones, social links, and page metadata. Up to 15 ads are crawled per request. Crawl results are cached for 7 days.
5. Return — Results are returned sorted by last_seen (most recent first), with is_active indicating whether each ad appeared in the current live search.

Credit Calculation

• Credits are based on fresh results only (historical and crawl enrichment are free).
• More than 7 fresh ads → 10 credits
• 7 or fewer fresh ads → 1 credit per ad containing an email
• No fresh ads → 0 credits (but historical results are still returned)

Places Search

Search Google Places for businesses by keyword. Returns detailed listings including name, address, phone, website, rating, business hours, and more. Results are cached for 30 days to save credits.

Parameters

Example Request

curl "https://leadgen.tools/v2/api/v1/places/search.php?\
api_key=YOUR_KEY&\
keyword=restaurants+new+york"

Example Response

{
  "status": "success",
  "credits_used": 40,
  "data": {
    "keyword": "restaurants new york",
    "results_count": 4,
    "next_page_token": "AeJbb3eFR...",
    "results": [
      {
        "url": "https://maps.google.com/?cid=...",
        "name": "Joe's Pizza",
        "address": "7 Carmine St, New York, NY 10014",
        "phone": "(212) 366-1182",
        "website": "https://www.joespizzanyc.com/",
        "rating": 4.4,
        "rating_total": 8732,
        "types": ["restaurant", "meal_delivery", "food"],
        "weekday_text": [
          "Monday: 10:00 AM \u2013 2:00 AM",
          "Tuesday: 10:00 AM \u2013 2:00 AM"
        ],
        "icon": "https://maps.gstatic.com/...",
        "open_now": true,
        "place_id": "ChIJr3_gqu5ZwokR...",
        "business_status": "OPERATIONAL",
        "cached": false
      }
    ]
  }
}

Response Fields

Pagination

Each request returns up to 20 results. If more results are available, the response includes a next_page_token. To fetch the next page:

curl "https://leadgen.tools/v2/api/v1/places/search.php?\
api_key=YOUR_KEY&\
keyword=restaurants+new+york&\
pagetoken=AeJbb3eFR..."

Credit Calculation

• 10 credits per place that requires a fresh Google API lookup (cache miss).
• 0 credits for places already in cache (within 30 days).
• Typical first search: ~20 places × 10 credits = 200 credits.
• Subsequent same search: 0 credits (all cached).

Place Reviews

Fetch Google reviews for a specific place. Use the place_id from the Places Search response. Reviews are cached for 7 days.

Parameters

Example Request

curl "https://leadgen.tools/v2/api/v1/places/reviews.php?\
api_key=YOUR_KEY&\
place_id=ChIJr3_gqu5ZwokR..."

Example Response

{
  "status": "success",
  "credits_used": 5,
  "data": {
    "place_id": "ChIJr3_gqu5ZwokR...",
    "reviews": [
      {
        "author_name": "John D.",
        "author_url": "https://www.google.com/maps/contrib/...",
        "language": "en",
        "rating": 5,
        "text": "Best pizza in NYC. Been coming here for 20 years!",
        "time": 1705330200,
        "relative_time_description": "a month ago",
        "profile_photo_url": "https://lh3.googleusercontent.com/..."
      }
    ],
    "cached": false
  }
}

Response Fields

Credit Calculation

• 5 credits for a fresh Google API call (cache miss).
• 0 credits if reviews are cached (within 7 days).
• If the Google API returns an error, 0 credits are deducted and an error response is returned.

Projects

Create and list projects. Projects are containers for leads and campaigns.

GET — List Projects

Example Response

{
  "status": "success",
  "credits_used": 0,
  "data": {
    "projects_count": 2,
    "projects": [
      {
        "id": 42,
        "name": "NYC Agencies",
        "type": "",
        "campaigns": [
          {"id": 8, "name": "Cold Outreach", "status": "active"}
        ]
      }
    ]
  }
}

POST — Create Project

Example

curl -X POST "https://leadgen.tools/v2/api/v1/projects.php?api_key=KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "NYC Marketing Agencies"}'

Leads

List and import leads into projects. Leads are the contacts that campaigns send emails to.

GET — List Leads

POST — Add Leads

Lead Object Fields

Example

curl -X POST "https://leadgen.tools/v2/api/v1/leads.php?api_key=KEY" \
  -H "Content-Type: application/json" \
  -d '{"project_id": 42, "leads": [{"email": "john@example.com", "firstname": "John"}]}'

Email Verification

Verify email addresses for deliverability. Checks domain, MX records, SPF, DKIM, DMARC, disposable email blocklist, and SMTP mailbox existence. Optionally updates lead records.

Example

curl -X POST "https://leadgen.tools/v2/api/v1/verify.php?api_key=KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["john@example.com", "bad@fake.xyz"], "lead_ids": [1234, 1235]}'

Sending Accounts

List connected sending accounts (Gmail OAuth and SMTP). These are used as sending_accounts when creating campaigns.

Campaigns

Create and list email campaigns. Campaigns are linked to a project (lead source) and one or more sending accounts.

GET — List Campaigns

Returns all campaigns for the authenticated user with summary stats.

GET — Campaign Detail (?id=X)

Returns full campaign with steps, recipient stats, and sending accounts.

POST — Create Campaign

Campaigns are created in draft status. Use the Launch endpoint to activate sending.

AI Email Generation

Generate a complete email sequence using AI (GPT-4o-mini). Returns spintax-powered subject lines and HTML bodies with merge fields. Pass the generated steps directly to the Create Campaign or Update Steps endpoint.

Update Campaign Steps

Replace all steps of a draft or paused campaign.

Launch Campaign

Launch a draft campaign. Validates steps and sending accounts, populates recipients from project leads, and sets status to active. Emails are sent by the server cron every 5 minutes (1 credit per email).

Campaign Control

Pause, resume, or cancel an active campaign.

State Transitions

Campaign Status

Lightweight endpoint for polling campaign progress. Returns campaign stats and per-status recipient counts.

Campaign Recipients

List recipients for a campaign with optional status filtering. Use ?status=replied to see who has responded.

Quick Reference

All endpoints at a glance:

Credit Summary

Changelog

v1.3 — February 2026

• Campaign Management API (OpenClaw): Full campaign lifecycle via API — create projects, import leads, verify emails, generate AI email sequences, create & launch campaigns, and monitor progress.
• New endpoints: Projects, Leads, Email Verification, Sending Accounts, Campaigns, AI Email Generation, Update Steps, Launch, Control, Status, Recipients.
• AI Email Generation: Generate spintax-powered email sequences with GPT-4o-mini. 1 credit per email generated.
• Email Verification: Domain, MX, SPF, DKIM, DMARC, disposable check, and SMTP deliverability validation.

v1.2 — February 2026

• Ad Spy — Historical ads: Ads are now stored permanently. Every search adds new ads to a historical database. Use first_seen, last_seen, and is_active to track ad lifespan and activity.
• Ad Spy — Crawl enrichment: Each ad's landing page is automatically crawled for emails, phones, social_links, and page metadata. Data is returned in the contact_data object on each result.
• Extended caching: Search cache increased from 1 hour to 7 days. Crawl cache increased from 24 hours to 14 days.
• New parameter: include_history on Ad Spy endpoint to control whether historical ads are included.

v1.1 — January 2026

• Places Search: Added Google Places Search endpoint with automatic caching.
• Place Reviews: Added Google Place Reviews endpoint with 7-day cache.

v1.0 — December 2025

• Initial release with Lead Search, Website Crawler, and Ad Spy endpoints.
• Softsale license key authentication.
• Credit-based billing with automatic caching.