Skip to main content

​
Quickstart

Get from zero to a working API call in 5 minutes.

​
Prerequisites

  • A Naturalead account with an organization set up
  • An API key (created from Settings > API Keys in the dashboard)

​
Step 1: Get your API key

Navigate to Settings > API Keys in your Naturalead dashboard and create a new key. Select the scopes you need (or use owner role for full access during development). Your key will look like: nl_live_a1b2c3d4...
The full API key is shown only once at creation. Store it securely — Naturalead only stores a hash.

​
Step 2: List your leads

curl -X GET "https://api.naturalead.ai/api/leads" \
  -H "X-API-Key: nl_live_YOUR_API_KEY"

​
Step 3: Create a lead

curl -X POST "https://api.naturalead.ai/api/leads" \
  -H "X-API-Key: nl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "phone": "+14155551234",
    "email": "[email protected]",
    "tags": ["demo", "quickstart"]
  }'
Phone numbers must be unique per account. If a lead with the same phone already exists, you’ll receive a 409 Conflict response.

​
Step 4: Start a conversation

Once you have a lead and an AI agent configured, start a conversation: 
curl -X POST "https://api.naturalead.ai/api/conversations/start" \
  -H "X-API-Key: nl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "leadId": 1,
    "channel": "whatsapp"
  }'
Available channels: whatsapp, telegram, email
You must configure the messaging integration (Twilio for WhatsApp, Telegram bot token, or Resend for email) before starting conversations on that channel.

​
What’s next?

Authentication

Learn about API keys, scopes, and token management.

Import Leads

Import leads from CSV files with field mapping.

Configure AI Agent

Set up your AI agent’s personality and knowledge base.

Launch a Campaign

Send batch outreach to qualified leads.