Frequently Asked Questions

Copy page

Frequently Asked Questions

General

What is LeadsDB?

LeadsDB is a lead management API that helps you store, search, and manage business leads. It provides a REST API for CRUD operations, advanced filtering, batch imports, and integrates with AI assistants via MCP (Model Context Protocol).

What can I use LeadsDB for?

• Lead collection: Store leads from web scrapers, forms, or manual entry
• Lead enrichment: Add custom attributes, tags, and notes
• Lead search: Filter and search leads with 20+ operators
• Lead scoring: Define custom scoring rules to prioritize leads
• AI integration: Connect Claude, Cursor, or other MCP clients to manage leads conversationally

Is there a free plan?

Yes! The free plan includes:

• Up to 500 leads
• 100 API requests per 10 minutes
• All core features (filtering, notes, attributes)
• MCP integration

Authentication

Where do I find my API key?

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

How do I authenticate API requests?

Include your API key in the X-API-Key header:

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

Can I regenerate my API key?

Currently, API keys are generated when your account is created. Contact support if you need to regenerate your key for security reasons.

Is my API key secure?

Yes. API keys are stored securely and transmitted over HTTPS. Never share your API key publicly or commit it to version control. Use environment variables to store it in your applications.

Leads

What fields are required when creating a lead?

Only two fields are required:

• name - The business or contact name
• source - Where the lead came from (e.g., "website", "import", "referral")

What are dynamic attributes?

Dynamic attributes let you store custom key-value pairs on leads. Each attribute has a name, type, and value:

Code
 
{
  "attributes": [
    {"name": "industry", "type": "text", "value": "Healthcare"},
    {"name": "annual_revenue", "type": "number", "value": 5000000},
    {"name": "is_verified", "type": "bool", "value": true}
  ]
}

Supported types: text, number, bool, list, object

How do I search leads by custom attributes?

Use the attr: prefix in filters:

Code
 
# Find leads where industry = "Healthcare"
curl "https://getleadsdb.com/api/v1/leads?filter=and.eq.attr:industry.Healthcare"

What's the maximum number of leads I can store?

• Free plan: 500 leads
• Pro plan: Higher limits based on subscription

Can I import leads in bulk?

Yes! Use the batch endpoint to create up to 100 leads per request:

Code
 
curl -X POST "https://getleadsdb.com/api/v1/leads/batch" \
  -H "X-API-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"leads": [...]}'

The response includes success/failure status for each lead.

How does full-text search work?

The name field supports fast prefix search using FTS (Full-Text Search). Use the contains operator:

Code
 
curl "https://getleadsdb.com/api/v1/leads?filter=and.contains.name.acme"

This finds leads with names containing "acme" (case-insensitive).

Filtering

What filter operators are available?

Text fields: eq, neq, contains, not_contains, is_empty, is_not_empty

Number fields: eq, neq, gt, gte, lt, lte

Arrays/Tags: array_contains, array_not_contains, array_empty, array_not_empty

Location: within_radius, is_set, is_not_set

Custom attributes: exists, not_exists

How do I combine multiple filters?

Use AND or OR logic by adding multiple filter parameters:

Code
 
# Leads in Athens AND rating >= 4
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"

How do I filter by location radius?

Use the within_radius operator with format lat,lng,radius_km:

Code
 
# Within 5km of Athens center (37.98, 23.73)
curl "https://getleadsdb.com/api/v1/leads?filter=and.within_radius.location.37.98,23.73,5"

What's the maximum number of filters?

You can use up to 20 filters per query.

Pagination

How does pagination work?

LeadsDB uses cursor-based pagination for efficient traversal:

Code
 
# First page
curl "https://getleadsdb.com/api/v1/leads?limit=50"

# Response
{
  "leads": [...],
  "next_cursor": "lead_01922a5b...",
  "has_more": true,
  "count": 50
}

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

What's the maximum page size?

You can request up to 1,000 leads per page using the limit parameter. Default is 50.

Scoring

How do scoring rules work?

Scoring rules are expressions that calculate a score (0-100) for each lead based on its fields. Scores are calculated when leads are created.

Example expression:

Code
 
(email != nil ? 30 : 0) + (phone != nil ? 30 : 0) + (rating ?? 0) * 8

What variables can I use in scoring expressions?

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

Can I recalculate scores for existing leads?

Yes! Use the "Apply to all leads" button on the Scoring Rules page to recalculate scores for all your leads.

Rate Limits

What are the rate limits?

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

How do I know my current rate limit status?

Every API response includes rate limit headers:

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

What happens when I exceed the rate limit?

You'll receive a 429 Too Many Requests response. Wait for the time indicated in the Retry-After header before retrying.

MCP Integration

What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI assistants to securely connect to external data sources. LeadsDB supports MCP, letting you manage leads through natural language conversations.

Which AI clients support MCP?

• Claude Desktop
• Cursor IDE
• Any MCP-compatible client

How do I set up MCP?

See the MCP Setup Guide for detailed instructions for each client.

What can I do with MCP?

• Search and filter leads: "Find restaurants in Paris with rating above 4"
• Create leads: "Add a new lead for Acme Corp, a software company"
• Update leads: "Add the 'vip' tag to all leads in the Technology category"
• Export data: "Export all leads with email addresses to CSV"

Technical

What format are timestamps in?

All timestamps are Unix timestamps (seconds since epoch). For example: 1703520000

What format are lead IDs in?

Lead IDs use UUIDv7 format with a lead_ prefix: lead_01922a5b-1234-7def-89ab-cdef01234567

UUIDv7 IDs are lexicographically sortable by creation time.

Is there a webhook system?

Not currently. Webhooks are on the roadmap for future releases.

Do you support OpenAPI/Swagger?

Yes! The OpenAPI specification is available at /api/openapi.yaml and you can explore the API interactively in the API Reference.

Troubleshooting

I'm getting a 401 Unauthorized error

This means your API key is missing or invalid. Check that:

1. You're including the API key in the X-API-Key header (not as a query parameter)
2. The API key is correct and hasn't been regenerated
3. There are no extra spaces or characters in the key

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

I'm getting a 400 Bad Request error

This usually means there's an issue with your request body or parameters. Common causes:

• Missing required fields (name and source are required for creating leads)
• Invalid JSON syntax
• Wrong data types (e.g., sending a string where a number is expected)
• Invalid filter format

Check the error message in the response body for specific details.

I'm getting a 403 Forbidden error

This means you've hit your plan's lead limit. Options:

1. Delete some existing leads to make room
2. Upgrade to a higher plan
3. Check your current lead count on the dashboard

I'm getting a 429 Too Many Requests error

You've exceeded your rate limit. The response includes a Retry-After header indicating how many seconds to wait.

Code
 
import time
import requests

response = requests.get(url, headers=headers)
if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    time.sleep(retry_after)
    response = requests.get(url, headers=headers)  # Retry

My filters aren't working

Check the filter format: logic.operator.field.value

Common mistakes:

• Wrong order: Use and.eq.city.Athens not city.eq.Athens
• Case sensitivity: Field names are case-sensitive (city not City)
• URL encoding: Spaces and special characters need encoding (San%20Francisco)
• Wrong operator: Use array_contains for tags, not eq

Code
 
# Correct
filter=and.eq.city.Athens
filter=and.array_contains.tags.vip
filter=and.gte.rating.4

# Wrong
filter=city.eq.Athens          # Wrong order
filter=and.eq.tags.vip         # Wrong operator for arrays

Batch create is failing for some leads

The batch endpoint returns a 207 Multi-Status response when some leads succeed and others fail. Check the errors array in the response:

Code
 
{
  "created": [...],
  "errors": [
    {"index": 2, "message": "Duplicate source_id"},
    {"index": 5, "message": "Name is required"}
  ],
  "total": 10,
  "success": 8,
  "failed": 2
}

Each error includes the index of the failed lead in your original array and the error message.

My leads aren't being found by search

If full-text search isn't returning expected results:

1. Use contains operator for name search, not eq
2. Search is case-insensitive but matches from the start of words
3. Wait a moment after creating leads for indexing

Code
 
# Good: prefix search
filter=and.contains.name.acme

# This will find "Acme Corp" but might not find "The Acme Company"

Location-based search returns no results

Check that:

1. Your leads have latitude and longitude set
2. The radius is in kilometers (not miles)
3. Coordinates are in the correct format: lat,lng,radius_km

Code
 
# Within 10km of coordinates
filter=and.within_radius.location.37.98,23.73,10

MCP tools aren't appearing in Claude/Cursor

1. Verify the configuration JSON syntax is correct
2. Restart the application after configuration changes
3. Check that the MCP endpoint is accessible: https://getleadsdb.com/mcp/sse
4. Look for error messages in the application logs

Support

How do I report a bug or request a feature?

Visit our Contact page to report issues or request features.

How do I contact support?

For any questions or account-related issues, visit our Contact page.