Introduction to LeadsDB

Copy page

LeadsDB API Documentation

LeadsDB is a lead management API that helps you store, search, and manage business leads. This documentation covers the REST API, authentication, filtering, and integration with AI assistants via MCP.

Features

• Lead Management: Create, read, update, and delete leads with rich metadata
• Dynamic Attributes: Store custom key-value pairs with type safety (text, number, boolean, list, object)
• Full-Text Search: Fast prefix search on lead names using FTS
• Advanced Filtering: 20+ operators for filtering by text, numbers, dates, tags, location, and custom attributes
• Notes: Attach notes to leads for tracking interactions
• Scoring Rules: Define custom scoring expressions to rank leads automatically
• Batch Operations: Create up to 100 leads in a single API call
• MCP Integration: Connect AI assistants (Claude, Cursor, etc.) directly to your leads
• Rate Limiting: Sliding window rate limiting with plan-based limits

Quick Start

1. Get Your API Key

Your API key is available on the Settings page after signing in. API keys have the format:

Code
 
sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2. Make Your First Request

Code
 
curl -X GET "https://getleadsdb.com/api/v1/leads" \
  -H "X-API-Key: sk_live_your_api_key_here"

3. Create a Lead

Code
 
curl -X POST "https://getleadsdb.com/api/v1/leads" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "source": "website",
    "category": "Technology",
    "city": "San Francisco",
    "country": "USA",
    "phone": "+1-555-0100",
    "email": "[email protected]",
    "website": "https://acme.com",
    "rating": 4.5,
    "review_count": 128,
    "tags": ["enterprise", "saas"],
    "attributes": [
      {"name": "industry", "type": "text", "value": "Software"},
      {"name": "employees", "type": "number", "value": 500},
      {"name": "verified", "type": "bool", "value": true}
    ]
  }'

Response:

Code
 
{
  "id": "lead_01234567-89ab-cdef-0123-456789abcdef",
  "message": "Lead created successfully",
  "created_at": 1703520000
}

Authentication

All API endpoints require authentication using your API key. Include it in your requests using one of these methods:

X-API-Key Header

Code
 
curl -H "X-API-Key: sk_live_your_api_key_here" \
  https://getleadsdb.com/api/v1/leads

Using API Keys in Documentation

Important: Zudoku documentation doesn't support API key authentication in the playground UI. You need to manually add your API key to each request.

To test API endpoints:

1. Copy your API key from the Settings page
2. For each API request you want to test:
   • Click the "Try it" button on any endpoint
   • In the request preview, click "Add header"
   • Add header: X-API-Key with your API key as the value
   • Execute the request

Example request headers:

Code
 
X-API-Key: sk_live_your_api_key_here

Alternatively, you can use these API testing tools that support API keys:

• Postman - Import the OpenAPI spec from /api/openapi.yaml
• Insomnia - Import the OpenAPI spec
• curl - Add -H "X-API-Key: your_key" to commands

Lead Model

Each lead contains the following fields:

Field	Type	Required	Description
name	string	Yes	Business or contact name
source	string	Yes	Where the lead came from
description	string	No	Detailed description
address	string	No	Street address
city	string	No	City name
state	string	No	State or province
country	string	No	Country name
postal_code	string	No	ZIP or postal code
latitude	number	No	GPS latitude
longitude	number	No	GPS longitude
phone	string	No	Phone number
email	string	No	Email address
website	string	No	Website URL
rating	number	No	Rating (typically 0-5)
review_count	integer	No	Number of reviews
category	string	No	Business category
tags	string[]	No	Array of tags
source_id	string	No	ID from the source system
logo_url	string	No	URL to business logo
attributes	object[]	No	Custom key-value pairs

Dynamic Attributes

Store custom data with type safety:

Code
 
{
  "attributes": [
    {"name": "cuisine", "type": "text", "value": "Italian"},
    {"name": "price_level", "type": "number", "value": 3},
    {"name": "accepts_cards", "type": "bool", "value": true},
    {"name": "payment_methods", "type": "list", "value": ["cash", "card", "crypto"]},
    {"name": "hours", "type": "object", "value": {"mon": "9-5", "tue": "9-5"}}
  ]
}

Filtering Leads

The API supports powerful filtering with multiple operators using the filter query parameter.

Filter Format: logic.operator.field.value

Code
 
# Leads in Athens with rating >= 4.0
curl "https://getleadsdb.com/api/v1/leads?filter=and.eq.city.Athens&filter=and.gte.rating.4"

# Leads with email OR phone
curl "https://getleadsdb.com/api/v1/leads?filter=and.is_not_empty.email&filter=or.is_not_empty.phone"

# Leads tagged as "restaurant"
curl "https://getleadsdb.com/api/v1/leads?filter=and.array_contains.tags.restaurant"

# Leads with custom attribute
curl "https://getleadsdb.com/api/v1/leads?filter=and.eq.attr:cuisine.Italian"

Available Operators

Text Fields

Operator	Description	Example
eq	Equals (case insensitive)	filter=and.eq.city.Athens
neq	Not equals	filter=and.neq.country.USA
contains	Contains substring	filter=and.contains.name.pizza
not_contains	Does not contain	filter=and.not_contains.name.test
is_empty	Is null or empty	filter=and.is_empty.email
is_not_empty	Has a value	filter=and.is_not_empty.phone

Number Fields

Operator	Description	Example
eq	Equals	filter=and.eq.rating.4.5
neq	Not equals	filter=and.neq.review_count.0
gt	Greater than	filter=and.gt.rating.4
gte	Greater than or equal	filter=and.gte.rating.4
lt	Less than	filter=and.lt.rating.3
lte	Less than or equal	filter=and.lte.review_count.10

Tags/Arrays

Operator	Description	Example
array_contains	Contains value	filter=and.array_contains.tags.vip
array_not_contains	Does not contain	filter=and.array_not_contains.tags.spam
array_empty	Array is empty	filter=and.array_empty.tags
array_not_empty	Array has items	filter=and.array_not_empty.tags

Location

Operator	Description	Example
within_radius	Within radius (km)	filter=and.within_radius.location.37.98,23.73,5
is_set	Has coordinates	filter=and.is_set.location
is_not_set	No coordinates	filter=and.is_not_set.location

Pagination & Sorting

Combine filters, pagination, and sorting in a single request:

Code
 
# Paginated, sorted, filtered results
curl "https://getleadsdb.com/api/v1/leads?filter=and.eq.city.Athens&filter=and.gte.rating.4&sort_by=rating&sort_order=DESC&limit=20"

# Next page using cursor
curl "https://getleadsdb.com/api/v1/leads?cursor=lead_01922a5b...&limit=20"

Parameters:

• limit: Maximum results per page (default: 50, max: 1000)
• cursor: Pagination cursor from previous response
• sort_by: Field to sort by
• sort_order: ASC or DESC (default: ASC)

Response:

Code
 
{
  "leads": [...],
  "next_cursor": "lead_01922a5b...",
  "has_more": true,
  "count": 20
}

Batch Operations

Create up to 100 leads in a single request:

Code
 
curl -X POST "https://getleadsdb.com/api/v1/leads/batch" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {"name": "Lead 1", "source": "import", "city": "Athens"},
      {"name": "Lead 2", "source": "import", "city": "London"},
      {"name": "Lead 3", "source": "import", "city": "Paris"}
    ]
  }'

Response (207 Multi-Status for partial success):

Code
 
{
  "created": [
    {"index": 0, "id": "lead_...", "created_at": 1703520000},
    {"index": 1, "id": "lead_...", "created_at": 1703520001}
  ],
  "errors": [
    {"index": 2, "message": "Duplicate source_id"}
  ],
  "total": 3,
  "success": 2,
  "failed": 1
}

Notes

Attach notes to leads for tracking interactions:

Code
 
# Add a note
curl -X POST "https://getleadsdb.com/api/v1/leads/lead_.../notes" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"content": "Called on Dec 15, interested in premium plan"}'

# Get notes for a lead
curl "https://getleadsdb.com/api/v1/leads/lead_.../notes" \
  -H "X-API-Key: sk_live_your_api_key_here"

Scoring Rules

Define custom scoring expressions to automatically rank leads. Scores are calculated when leads are created and can be recalculated in bulk.

Expression Variables

Variable	Type	Description
rating	number	Lead rating (0-5)
review_count	number	Number of reviews
email	string	Email address (nil if not set)
phone	string	Phone number (nil if not set)
website	string	Website URL (nil if not set)
city	string	City name
country	string	Country name
tags	string[]	Array of tags

Example Expressions

Code
 
// Simple: Rating-based score (0-100)
rating * 20

// Contact completeness scoring
(email != nil ? 30 : 0) + (phone != nil ? 30 : 0) + (website != nil ? 20 : 0) + (rating ?? 0) * 4

// Complex scoring with caps
let quality = (rating ?? 0) * 15;
let reviews = min(review_count ?? 0, 200) / 4;
let contact = (email != nil ? 20 : 0) + (phone != nil ? 15 : 0) + (website != nil ? 10 : 0);
quality + reviews + contact

Scores are automatically clamped to the 0-100 range.

Rate Limits

API requests are rate-limited using a sliding window algorithm.

Plan	Limit	Window
Free	100 requests	10 minutes
Pro	1,000 requests	10 minutes

Rate Limit Headers

Every response includes rate limit information:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Remaining requests
Retry-After	Seconds to wait (when rate limited)

Rate Limit Exceeded Response

Code
 
{
  "error": "Rate limit exceeded"
}

HTTP Status: 429 Too Many Requests

Error Handling

All errors follow a consistent format:

Code
 
{
  "error": "Error message",
  "message": "Detailed description",
  "code": "error_code"
}

Common Error Codes

Status	Description
400	Invalid request body or parameters
401	Missing or invalid API key
403	Leads limit reached (upgrade required)
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Next Steps

• API Reference - Complete endpoint documentation with interactive examples
• MCP Setup Guide - Connect AI assistants to your leads
• Changelog - API version history
• FAQ - Common questions, troubleshooting, and answers