> ## Documentation Index
> Fetch the complete documentation index at: https://docs.naturalead.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# cURL Examples

> Command-line examples for the Naturalead API

# cURL Examples

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

## Leads

### List all leads

```bash theme={null}
curl -s "https://api.naturalead.ai/api/leads" \
  -H "X-API-Key: YOUR_API_KEY" | jq
```

### Search leads

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

### Create a lead

```bash theme={null}
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": "jane@example.com",
    "tags": ["inbound", "demo"]
  }'
```

### Update lead status

```bash theme={null}
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

```bash theme={null}
curl -X DELETE "https://api.naturalead.ai/api/leads/1" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Lead Sync

### Bulk sync leads from CRM

```bash theme={null}
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": "alice@example.com"},
      {"lead_id": "crm-002", "name": "Bob", "phone": "+0987654321"}
    ]
  }'
```

### Bulk delete synced leads

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

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

## Campaigns

### Create a campaign

```bash theme={null}
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

```bash theme={null}
curl -X POST "https://api.naturalead.ai/api/campaigns/CAMPAIGN_ID/launch" \
  -H "X-API-Key: YOUR_API_KEY"
```

## Analytics

### Get overview stats

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

## Audit Logs

### Query audit logs

```bash theme={null}
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

```bash theme={null}
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
```