cURL Examples

All examples use the X-API-Key header for authentication. Replace YOUR_API_KEY with your actual key.

Leads

List all leads

curl -s "https://api.naturalead.ai/api/leads" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Incremental sync (leads updated since a timestamp)

curl -s "https://api.naturalead.ai/api/leads?updatedAfter=2026-06-01T00:00:00Z&page=1&limit=50&sortBy=updatedAt&sortOrder=asc" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Search leads

curl -s "https://api.naturalead.ai/api/leads/search?q=john&limit=5" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Create a lead

curl -X POST "https://api.naturalead.ai/api/leads" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "phone": "+14155551234",
    "email": "[email protected]",
    "tags": ["inbound", "demo"]
  }'

Update lead outreach status

curl -X PATCH "https://api.naturalead.ai/api/leads/1" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "contacted"}'

Delete a lead

curl -X DELETE "https://api.naturalead.ai/api/leads/1" \
  -H "X-API-Key: YOUR_API_KEY"

Lead Sync

Bulk sync leads from CRM

curl -X POST "https://api.naturalead.ai/api/leads/sync" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leads": [
      {"lead_id": "crm-001", "name": "Alice", "phone": "+1234567890", "email": "[email protected]"},
      {"lead_id": "crm-002", "name": "Bob", "phone": "+0987654321"}
    ]
  }'

Bulk delete synced leads

curl -X DELETE "https://api.naturalead.ai/api/leads/sync" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lead_ids": ["crm-001", "crm-002"]}'

Conversations

Start a conversation

curl -X POST "https://api.naturalead.ai/api/conversations/start" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"leadId": 1, "channel": "whatsapp"}'

Send a message

curl -X POST "https://api.naturalead.ai/api/conversations/CONVERSATION_ID/send" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, are you interested in our product?"}'

List conversations

curl -s "https://api.naturalead.ai/api/conversations?status=active" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Incremental sync (conversations updated since a timestamp)

curl -s "https://api.naturalead.ai/api/conversations?updatedAfter=2026-06-01T00:00:00Z&page=1&limit=50&sortBy=updatedAt&sortOrder=asc" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Lead Insights

Structured key points extracted from chats (same data as the dashboard Lead Insights sidebar). Preferred CRM sync payload over conversation summary.

List insights for a lead

curl -s "https://api.naturalead.ai/api/preferences/LEAD_ID" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Requires conversations:view. Path id is the lead id (not a preference document id).

Campaigns

Create a campaign

curl -X POST "https://api.naturalead.ai/api/campaigns" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Outreach",
    "agentConfigId": "AGENT_ID",
    "channel": "whatsapp",
    "leadFilter": {"statuses": ["new"], "tags": ["inbound"]},
    "schedule": {"rateLimit": 10}
  }'

Launch a campaign

curl -X POST "https://api.naturalead.ai/api/campaigns/CAMPAIGN_ID/launch" \
  -H "X-API-Key: YOUR_API_KEY"

Analytics

Get overview stats

curl -s "https://api.naturalead.ai/api/analytics/overview?range=30d" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Audit Logs

Query audit logs

curl -s "https://api.naturalead.ai/api/audit-logs?action=lead.created&limit=10" \
  -H "X-API-Key: YOUR_API_KEY" | jq

Export as CSV

curl -s "https://api.naturalead.ai/api/audit-logs/export?format=csv&from=2026-01-01" \
  -H "X-API-Key: YOUR_API_KEY" \
  -o audit-logs.csv

​cURL Examples

​Leads

​List all leads

​Incremental sync (leads updated since a timestamp)

​Search leads

​Create a lead

​Update lead outreach status

​Delete a lead

​Lead Sync

​Bulk sync leads from CRM

​Bulk delete synced leads

​Conversations

​Start a conversation

​Send a message

​List conversations

​Incremental sync (conversations updated since a timestamp)

​Lead Insights

​List insights for a lead

​Campaigns

​Create a campaign

​Launch a campaign

​Analytics

​Get overview stats

​Audit Logs

​Query audit logs

​Export as CSV