API Reference - FreshLeads.pro | Lead Generation API Documentation

Overview

The FreshLeads API uses standard HTTP methods. All responses are JSON. Authentication is via Bearer token.

💡 All API requests require an API key. Get yours from the Dashboard under Settings > API Keys.

Header	Value
Authorization	Bearer YOUR_API_KEY
Content-Type	application/json

Authentication

Obtain an API token using your account credentials.

POST /auth/token Get API token ▼

Request Body

Parameter	Type	Description
emailrequired	string	Your account email
passwordrequired	string	Your account password

                                    
                                    
                                    
                                    
                                
curl -X POST https://www.freshleads.pro/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your_password"}'
const res = await fetch('https://www.freshleads.pro/api/v1/auth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'you@example.com',
    password: 'your_password'
  })
});
const { token } = await res.json();
import requests

res = requests.post('https://www.freshleads.pro/api/v1/auth/token', json={
    'email': 'you@example.com',
    'password': 'your_password'
})
token = res.json()['token']

✅ Response 200

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 86400,
  "plan": "growth"
}

Search

Search Google Maps for businesses in real-time. This is the core of FreshLeads.

POST /search Search Google Maps for businesses ▼

Request Body

Parameter	Type	Description
queryrequired	string	Business type, e.g. "dentists", "plumbers", "restaurants"
locationrequired	string	City, ZIP code, or coordinates. E.g. "Miami, FL" or "33101"
limitoptional	integer	Max results (10-500). Default: 20
verify_emailsoptional	boolean	Enable email verification. Default: true

                                    
                                    
                                    
                                    
                                
curl -X POST https://www.freshleads.pro/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "dentists",
    "location": "Miami, FL",
    "limit": 50,
    "verify_emails": true
  }'
const res = await fetch('https://www.freshleads.pro/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'dentists',
    location: 'Miami, FL',
    limit: 50
  })
});
const { search_id } = await res.json();
import requests

res = requests.post(
    'https://www.freshleads.pro/api/v1/search',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'query': 'dentists',
        'location': 'Miami, FL',
        'limit': 50
    }
)
search_id = res.json()['search_id']

✅ Response 201

{
  "search_id": "srch_abc123",
  "status": "processing",
  "estimated_results": 50
}

GET /search/:id/status Check search progress ▼

✅ Response 200

{
  "search_id": "srch_abc123",
  "status": "completed",
  "progress": 100,
  "total_results": 47,
  "emails_found": 32
}

GET /search/:id/results Get search results with full lead data ▼

📌 Each lead includes up to 14 data fields extracted from Google Maps in real-time.

✅ Response 200

{
  "results": [
    {
      "business_name": "Smile Dental Miami",
      "phone": "+1 (305) 555-0123",
      "email": "info@smiledental.com",
      "website": "https://smiledental.com",
      "address": "123 Brickell Ave, Miami, FL 33131",
      "city": "Miami",
      "state": "FL",
      "zip_code": "33131",
      "rating": 4.8,
      "reviews": 247,
      "category": "Dentist",
      "hours": "Mon-Fri 9AM-6PM",
      "google_maps_url": "https://maps.google.com/...",
      "owner_name": "Dr. Sarah Johnson"
    }
  ],
  "total": 47,
  "page": 1
}

Leads

Manage your extracted leads.

GET/leadsList all leads with pagination▼

Query Parameters

Parameter	Type	Description
pageoptional	integer	Page number (default: 1)
per_pageoptional	integer	Results per page (default: 50, max: 200)
searchoptional	string	Filter by business name or email

GET/leads/:idGet single lead details▼

Returns the full lead object with all 14 data fields.

DELETE/leads/:idDelete a lead▼

✅ Response 200

{ "deleted": true }

Export

Download your leads in multiple formats, ready for your outreach tools.

GET/export/:projectIdExport leads (Excel default)▼

Query Parameters

Parameter	Type	Description
formatoptional	string	Export format: `xlsx`, `csv`, `instantly`, `lemlist`, `smartlead`

📦Each format is pre-structured for direct import. Instantly, Lemlist, and Smartlead exports include the exact columns these tools expect.

CRM

Manage leads in the built-in CRM.

GET/crm/leadsList CRM leads▼

Returns leads added to your CRM pipeline with status, notes, and tasks.

POST/crm/leadsAdd lead to CRM▼

Request Body

Parameter	Type	Description
lead_idrequired	string	Lead ID from search results
statusoptional	string	new, contacted, qualified, converted, lost
notesoptional	string	Notes about the lead

GET/crm/analyticsCRM analytics and metrics▼

Returns pipeline metrics: total leads, conversion rates, status breakdown, and activity timeline.

Webhooks

Get notified when events happen in your account.

POST/webhooksRegister a webhook▼

Request Body

Parameter	Type	Description
urlrequired	string	Your webhook endpoint URL
eventsrequired	array	Events: search.completed, export.ready, lead.created

🖂 Webhook Payload Example

{
  "event": "search.completed",
  "data": {
    "search_id": "srch_abc123",
    "total_results": 47,
    "emails_found": 32
  },
  "timestamp": "2025-01-15T10:30:00Z",
  "signature": "sha256=abc123..."
}

Error Codes

Standard HTTP status codes are used for all responses.

Code	Status	Description
200	OK	Request succeeded
201	Created	Resource created (search started)
400	Bad Request	Invalid parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Plan limit reached
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal error — try again

// Error response format
{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retry_after": 60
  }
}

SDKs & Libraries

Official client libraries for popular languages.

Coming Soon

🐍

Python

pip install freshleads

Coming Soon

⚙️

Node.js

npm install freshleads

Coming Soon

🐘

PHP

composer require freshleads

Coming Soon

💎

Ruby

gem install freshleads