Skip to main content

​
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:
MethodHeaderFormat
API KeyX-API-Keynl_live_<key> or nl_test_<key>
Bearer TokenAuthorizationBearer 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:
ParameterTypeDefaultDescription
skipinteger0Number of records to skip
limitinteger50Maximum 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

OperatorDescriptionExample
isExact match{ "field": "status", "operator": "is", "value": "new" }
is_notNot equal{ "field": "status", "operator": "is_not", "value": "disqualified" }
containsSubstring match{ "field": "name", "operator": "contains", "value": "john" }
is_any_ofIn list{ "field": "status", "operator": "is_any_of", "value": ["new", "contacted"] }
includes_any_ofArray overlap{ "field": "tags", "operator": "includes_any_of", "value": ["vip"] }
is_beforeDate comparison{ "field": "createdAt", "operator": "is_before", "value": "2026-01-01" }
is_afterDate 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

DomainBase PathDescription
Leads/api/leadsLead management and import
Lead Sync/api/leads/syncBulk CRM synchronization
Conversations/api/conversationsAI-driven conversations
Campaigns/api/campaignsBatch outreach campaigns
Agent Config/api/agent-configAI agent configuration
Knowledge Bases/api/knowledge-basesDocument and content management
Analytics/api/analyticsReporting and metrics
A/B Testing/api/ab-testsAgent experiment management
Audit Logs/api/audit-logsCompliance and monitoring
Integrations/api/integrationsChannel configuration
API Keys/api/api-keysKey lifecycle management
Accounts/api/accountsOrganization and team management
Webhooks/api/webhooksInbound message handling