> ## 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.

# Quickstart

> Make your first API call in under 5 minutes

# 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...`

<Warning>
  The full API key is shown only once at creation. Store it securely — Naturalead only stores a hash.
</Warning>

## Step 2: List your leads

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.naturalead.ai/api/leads" \
    -H "X-API-Key: nl_live_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.naturalead.ai/api/leads",
      headers={"X-API-Key": "nl_live_YOUR_API_KEY"}
  )

  leads = response.json()
  print(f"Found {len(leads)} leads")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.naturalead.ai/api/leads", {
    headers: { "X-API-Key": "nl_live_YOUR_API_KEY" }
  });

  const leads = await response.json();
  console.log(`Found ${leads.length} leads`);
  ```
</CodeGroup>

## Step 3: Create a lead

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

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.naturalead.ai/api/leads",
      headers={
          "X-API-Key": "nl_live_YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "name": "Jane Smith",
          "phone": "+14155551234",
          "email": "jane@example.com",
          "tags": ["demo", "quickstart"]
      }
  )

  lead = response.json()
  print(f"Created lead #{lead['id']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.naturalead.ai/api/leads", {
    method: "POST",
    headers: {
      "X-API-Key": "nl_live_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      name: "Jane Smith",
      phone: "+14155551234",
      email: "jane@example.com",
      tags: ["demo", "quickstart"]
    })
  });

  const lead = await response.json();
  console.log(`Created lead #${lead.id}`);
  ```
</CodeGroup>

<Info>
  Phone numbers must be unique per account. If a lead with the same phone already exists, you'll receive a `409 Conflict` response.
</Info>

## Step 4: Start a conversation

Once you have a lead and an AI agent configured, start a conversation:

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.naturalead.ai/api/conversations/start",
      headers={
          "X-API-Key": "nl_live_YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json={
          "leadId": 1,
          "channel": "whatsapp"
      }
  )

  conversation = response.json()
  print(f"Conversation started: {conversation['_id']}")
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.naturalead.ai/api/conversations/start", {
    method: "POST",
    headers: {
      "X-API-Key": "nl_live_YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      leadId: 1,
      channel: "whatsapp"
    })
  });

  const conversation = await response.json();
  console.log(`Conversation started: ${conversation._id}`);
  ```
</CodeGroup>

Available channels: `whatsapp`, `telegram`, `email`

<Note>
  You must configure the messaging integration (WhatsApp Business API (Meta), Telegram bot token, or Resend for email) before starting conversations on that channel.
</Note>

## What's next?

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/authentication">
    Learn about API keys, scopes, and token management.
  </Card>

  <Card title="Import Leads" icon="file-import" href="/guides/csv-import-workflow">
    Import leads from CSV files with field mapping.
  </Card>

  <Card title="Configure AI Agent" icon="robot" href="/guides/configure-ai-agent">
    Set up your AI agent's personality and knowledge base.
  </Card>

  <Card title="Launch a Campaign" icon="rocket" href="/guides/launch-first-campaign">
    Send batch outreach to qualified leads.
  </Card>
</CardGroup>