REST API

Leadloadz REST API Documentation

Integrate B2B lead search and email verification into your applications with our comprehensive REST API.

Fast Response

Sub-200ms average response time for all endpoints.

Secure

Token-based auth with HTTPS only. SHA-256 hashed tokens.

SDKs

Python and Node.js SDKs with type definitions.

Overview

The Leadloadz REST API provides programmatic access to B2B lead search, email verification, and user management. All API requests require authentication and are served over HTTPS.

Base URL: https://leadloadz.com/api

Content-Type: application/json

Authentication

The API uses Bearer token authentication. Two types of tokens are supported:

1. Supabase Session Token

Used for user-facing endpoints (leads, verify, history). Obtained from user login.

Authorization: Bearer <SUPABASE_SESSION_TOKEN>

2. API Token (for MCP)

Used for MCP server access. Generated from the dashboard.

Authorization: Bearer <API_TOKEN>

Getting Your Token

Generate API tokens from your dashboard. Free tier includes 1 token.

Endpoints

POST/api/leads/fetch

Search Leads

Search for B2B leads using natural language or structured criteria.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "query": "CTOs at Series A B2B SaaS in London",
  "limit": 10
}

Response:

{
  "success": true,
  "leads": [
    {
      "name": "Jane Smith",
      "title": "CTO",
      "company": "TechCorp",
      "email": "jane@techcorp.com",
      "verified": true,
      "location": "London, UK",
      "industry": "Software",
      "company_size": "50-200"
    }
  ],
  "total": 1,
  "searchId": "uuid"
}

Error Responses:

401 Unauthorized429 Rate limit exceeded400 Invalid query

POST/api/verify-email

Verify Email

Verify an email address in real-time using MX, SMTP, and disposable domain checks.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "email": "jane@techcorp.com"
}

Response:

{
  "email": "jane@techcorp.com",
  "valid": true,
  "mx_valid": true,
  "smtp_valid": true,
  "disposable": false,
  "role_account": false,
  "catch_all": false,
  "score": 95,
  "message": "Email is valid and deliverable"
}

Error Responses:

401 Unauthorized429 Rate limit exceeded400 Invalid email format

GET/api/tokens

List API Tokens

List all active API tokens for the authenticated user.

Auth: Bearer token (Supabase session token)

Response:

{
  "tokens": [
    {
      "id": "uuid",
      "name": "Production Token",
      "token_prefix": "lead_",
      "scopes": ["leads:read", "verify:read"],
      "last_used_at": "2026-05-09T10:00:00Z",
      "created_at": "2026-05-01T00:00:00Z"
    }
  ]
}

Error Responses:

401 Unauthorized500 Server error

POST/api/tokens

Create API Token

Create a new API token for MCP server access.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "name": "My Agent Token",
  "scopes": ["leads:read", "verify:read"]
}

Response:

{
  "token": "leadloadz_live_xxxxxxxxxxxxxxxx",
  "token_id": "uuid",
  "name": "My Agent Token",
  "scopes": ["leads:read", "verify:read"],
  "created_at": "2026-05-09T10:00:00Z"
}

Error Responses:

401 Unauthorized400 Invalid request500 Server error

GET/api/tracking/history

Get Search History

Get the user's lead search and export history.

Auth: Bearer token (Supabase session token)

Response:

{
  "history": [
    {
      "id": "uuid",
      "query": "CTOs in London",
      "results_count": 10,
      "created_at": "2026-05-09T10:00:00Z"
    }
  ]
}

Error Responses:

401 Unauthorized

Rate Limits

Endpoint	Limit	Window
POST /api/leads/fetch	3/day (free), unlimited (pro)	Daily
POST /api/verify-email	20/min	Per IP
GET /api/tokens	30/min	Per IP
POST /api/tokens	10/min	Per IP
GET /api/tracking/history	30/min	Per IP
POST /api/mcp	30/min	Per user

SDKs

Python

Install:

pip install leadloadz

import leadloadz

client = leadloadz.Client(api_key="your-api-token")

# Search leads
leads = client.search_leads(
    query="CTOs at Series A B2B SaaS in London",
    limit=10
)

# Verify email
result = client.verify_email("jane@techcorp.com")
print(result.valid)  # True

Node.js / TypeScript

Install:

npm install @leadloadz/sdk

import { LeadloadzClient } from "@leadloadz/sdk";

const client = new LeadloadzClient({
  apiKey: "your-api-token"
});

// Search leads
const leads = await client.searchLeads({
  query: "CTOs at Series A B2B SaaS in London",
  limit: 10
});

// Verify email
const result = await client.verifyEmail("jane@techcorp.com");
console.log(result.valid); // true

Error Codes

Code	Message	Description
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid authentication token
429	Rate Limit Exceeded	Too many requests, retry after window
500	Internal Server Error	Server error, try again later

Ready to Integrate?

Get your free API token and start building with Leadloadz.

Authentication

The API uses Bearer token authentication. Two types of tokens are supported:

1. Supabase Session Token

Used for user-facing endpoints (leads, verify, history). Obtained from user login.

Authorization: Bearer <SUPABASE_SESSION_TOKEN>

2. API Token (for MCP)

Used for MCP server access. Generated from the dashboard.

Authorization: Bearer <API_TOKEN>

Getting Your Token

Generate API tokens from your dashboard. Free tier includes 1 token.

Endpoints

POST/api/leads/fetch

Search Leads

Search for B2B leads using natural language or structured criteria.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "query": "CTOs at Series A B2B SaaS in London",
  "limit": 10
}

Response:

{
  "success": true,
  "leads": [
    {
      "name": "Jane Smith",
      "title": "CTO",
      "company": "TechCorp",
      "email": "jane@techcorp.com",
      "verified": true,
      "location": "London, UK",
      "industry": "Software",
      "company_size": "50-200"
    }
  ],
  "total": 1,
  "searchId": "uuid"
}

Error Responses:

401 Unauthorized429 Rate limit exceeded400 Invalid query

POST/api/verify-email

Verify Email

Verify an email address in real-time using MX, SMTP, and disposable domain checks.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "email": "jane@techcorp.com"
}

Response:

{
  "email": "jane@techcorp.com",
  "valid": true,
  "mx_valid": true,
  "smtp_valid": true,
  "disposable": false,
  "role_account": false,
  "catch_all": false,
  "score": 95,
  "message": "Email is valid and deliverable"
}

Error Responses:

401 Unauthorized429 Rate limit exceeded400 Invalid email format

GET/api/tokens

List API Tokens

List all active API tokens for the authenticated user.

Auth: Bearer token (Supabase session token)

Response:

{
  "tokens": [
    {
      "id": "uuid",
      "name": "Production Token",
      "token_prefix": "lead_",
      "scopes": ["leads:read", "verify:read"],
      "last_used_at": "2026-05-09T10:00:00Z",
      "created_at": "2026-05-01T00:00:00Z"
    }
  ]
}

Error Responses:

401 Unauthorized500 Server error

POST/api/tokens

Create API Token

Create a new API token for MCP server access.

Auth: Bearer token (Supabase session token)

Request Body:

{
  "name": "My Agent Token",
  "scopes": ["leads:read", "verify:read"]
}

Response:

{
  "token": "leadloadz_live_xxxxxxxxxxxxxxxx",
  "token_id": "uuid",
  "name": "My Agent Token",
  "scopes": ["leads:read", "verify:read"],
  "created_at": "2026-05-09T10:00:00Z"
}

Error Responses:

401 Unauthorized400 Invalid request500 Server error

GET/api/tracking/history

Get Search History

Get the user's lead search and export history.

Auth: Bearer token (Supabase session token)

Response:

{
  "history": [
    {
      "id": "uuid",
      "query": "CTOs in London",
      "results_count": 10,
      "created_at": "2026-05-09T10:00:00Z"
    }
  ]
}

Error Responses:

401 Unauthorized

Endpoint

Limit

Window

POST /api/leads/fetch

3/day (free), unlimited (pro)

Daily

POST /api/verify-email

20/min

Per IP

GET /api/tokens

30/min

Per IP

POST /api/tokens

10/min

Per IP

GET /api/tracking/history

30/min

Per IP

POST /api/mcp

30/min

Per user

SDKs

Python

Install:

pip install leadloadz

import leadloadz

client = leadloadz.Client(api_key="your-api-token")

# Search leads
leads = client.search_leads(
    query="CTOs at Series A B2B SaaS in London",
    limit=10
)

# Verify email
result = client.verify_email("jane@techcorp.com")
print(result.valid)  # True

Node.js / TypeScript

Install:

npm install @leadloadz/sdk

import { LeadloadzClient } from "@leadloadz/sdk";

const client = new LeadloadzClient({
  apiKey: "your-api-token"
});

// Search leads
const leads = await client.searchLeads({
  query: "CTOs at Series A B2B SaaS in London",
  limit: 10
});

// Verify email
const result = await client.verifyEmail("jane@techcorp.com");
console.log(result.valid); // true

Code

Message

Description

400

Bad Request

Invalid request body or parameters

401

Unauthorized

Missing or invalid authentication token

429

Rate Limit Exceeded

Too many requests, retry after window

500

Internal Server Error

Server error, try again later