API Overview

Base URL

All API requests should be made to:

https://api.naturalead.ai/api

Authentication

Every request must include an API key via one of:

Method	Header	Format
API Key	`X-API-Key`	`nl_live_<key>` or `nl_test_<key>`
Bearer Token	`Authorization`	`Bearer nl_live_<key>` or `Bearer nl_test_<key>`

See Authentication for full details.

Content Type

All request bodies must be JSON:

Content-Type: application/json

Pagination

Paginated endpoints use skip and limit query parameters:

Parameter	Type	Default	Description
`skip`	integer	`0`	Number of records to skip
`limit`	integer	`50`	Maximum records to return

Paginated responses vary by endpoint. Common formats include:

{
  "data": [...],
  "total": 150,
  "skip": 0,
  "limit": 50
}

Some endpoints (e.g., leads with filters) return:

{
  "leads": [...],
  "total": 150
}

Filtering

Many list endpoints support filtering via query parameters. The leads API also supports advanced filtering via POST request bodies with complex conditions.

Filter operators

Operator	Description	Example
`is`	Exact match	`{ "field": "status", "operator": "is", "value": "new" }`
`is_not`	Not equal	`{ "field": "status", "operator": "is_not", "value": "disqualified" }`
`contains`	Substring match	`{ "field": "name", "operator": "contains", "value": "john" }`
`is_any_of`	In list	`{ "field": "status", "operator": "is_any_of", "value": ["new", "contacted"] }`
`includes_any_of`	Array overlap	`{ "field": "tags", "operator": "includes_any_of", "value": ["vip"] }`
`is_before`	Date comparison	`{ "field": "createdAt", "operator": "is_before", "value": "2026-01-01" }`
`is_after`	Date comparison	`{ "field": "createdAt", "operator": "is_after", "value": "2026-01-01" }`

Rate Limits

All responses include rate limit headers (IETF draft-7):

RateLimit-Limit: 1000
RateLimit-Remaining: 742
RateLimit-Reset: 34

See Rate Limits for tier details.

Error Format

All errors return a consistent JSON structure:

{
  "error": "Human-readable error message",
  "details": "Additional context (optional)"
}

See Error Reference for all error codes.

Request IDs

All requests are logged with a correlation ID for debugging. When contacting support, include the timestamp and endpoint of your request.

API Domains

Domain	Base Path	Description
Leads	`/api/leads`	Lead management and import
Lead Sync	`/api/leads/sync`	Bulk CRM synchronization
Conversations	`/api/conversations`	AI-driven conversations
Campaigns	`/api/campaigns`	Batch outreach campaigns
Agent Config	`/api/agent-config`	AI agent configuration
Knowledge Bases	`/api/knowledge-bases`	Document and content management
Analytics	`/api/analytics`	Reporting and metrics
A/B Testing	`/api/ab-tests`	Agent experiment management
Audit Logs	`/api/audit-logs`	Compliance and monitoring
Integrations	`/api/integrations`	Channel configuration
API Keys	`/api/api-keys`	Key lifecycle management
Accounts	`/api/accounts`	Organization and team management
Webhooks	`/api/webhooks`	Inbound message handling

List Leads

​API Overview

​Base URL

​Authentication

​Content Type

​Pagination

​Filtering

​Filter operators

​Rate Limits

​Error Format

​Request IDs

​API Domains