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

# Capture and Manage Leads from Your BotSmith Widget

> Enable lead capture in your BotSmith widget to collect visitor name and phone number, then view and manage leads from the Leads dashboard.

BotSmith can capture lead information — name and phone number — directly inside your chat widget. Leads are stored in your account and can be viewed and searched from the Leads dashboard.

<Note>
  The Leads dashboard is available on the Starter plan and higher. Free plan accounts must upgrade to access lead management features.
</Note>

## Enabling Lead Capture

<Steps>
  <Step title="Open the agent builder">
    Navigate to your agent from the **Dashboard** and click to open it.
  </Step>

  <Step title="Go to Settings">
    Click the **Settings** tab in the agent builder.
  </Step>

  <Step title="Toggle on Lead Capture">
    Scroll to **Lead Capture Form** and toggle it **On**.
  </Step>
</Steps>

The lead form activates immediately. Visitors will see it the next time they open your widget.

## What Visitors See

When lead capture is enabled, a short form appears inside the chat widget prompting visitors to enter their **name** and **phone number**. Both fields are required — the form cannot be submitted until both are filled in.

Once a visitor submits the form, they continue seamlessly into the chat. The lead is captured in the background and added to your account instantly.

## Viewing Leads

Navigate to **Leads** in the sidebar to see all leads captured across your agents. Each row in the leads table shows:

| Column          | Description                                     |
| --------------- | ----------------------------------------------- |
| **Name**        | The name the visitor entered in the lead form   |
| **Phone**       | The phone number the visitor entered            |
| **Agent**       | Which of your agents captured the lead          |
| **Date & Time** | The exact timestamp when the form was submitted |

## Lead Alerts

BotSmith can send you an email notification each time a new lead is captured. To configure the address that receives these alerts:

<Steps>
  <Step title="Open Lead Capture settings">
    In the agent builder, go to **Settings** and find the **Lead Capture Form** section.
  </Step>

  <Step title="Enable email alerts">
    Toggle on **Email Alerts** and enter the email address you want notifications sent to.
  </Step>

  <Step title="Save">
    Click **Save** to apply the changes.
  </Step>
</Steps>

Each agent can have its own alert address, so you can route notifications to different team members.

## Plan Limits

The number of leads you can store depends on your plan. When you reach your limit, the lead form continues to work for visitors, but new submissions are rejected until you upgrade.

| Plan             | Lead Storage                            |
| ---------------- | --------------------------------------- |
| **Free**         | Not available — upgrade to access leads |
| **Starter**      | 100 leads                               |
| **Professional** | 500 leads                               |

To view your current usage, check the **Leads Used** counter in the top-right of the Leads page.

## Lead API

You can retrieve and create leads programmatically via the REST API. See the [Leads API Reference](/api-reference/leads) for full details.

To retrieve all leads for your account:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://app.botsmith.ai/api/leads"
```

Each lead in the response includes:

| Field        | Type     | Description                      |
| ------------ | -------- | -------------------------------- |
| `id`         | string   | Unique lead identifier           |
| `name`       | string   | Visitor's name                   |
| `phone`      | string   | Visitor's phone number           |
| `chatbot_id` | string   | The agent that captured the lead |
| `created_at` | datetime | When the lead was captured       |

## Public Lead Capture Endpoint

To submit a lead directly from a custom integration — for example, a hand-coded widget or a native mobile app — use the public lead capture endpoint. No authentication token is required; BotSmith validates the chatbot ID server-side:

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/public/lead/YOUR_CHATBOT_ID \
  -H "Content-Type: application/json" \
  -d '{"name": "Jane Smith", "phone": "+1-555-0100"}'
```

Replace `YOUR_CHATBOT_ID` with the agent's ID from the agent builder URL.

<CodeGroup>
  ```json Request body theme={null}
  {
    "name": "Jane Smith",
    "phone": "+1-555-0100"
  }
  ```

  ```json Response theme={null}
  {
    "id": "lead_abc123",
    "chatbot_id": "bot_xyz789",
    "name": "Jane Smith",
    "phone": "+1-555-0100",
    "created_at": "2025-01-15T10:30:00Z"
  }
  ```
</CodeGroup>

Both `name` and `phone` are required. Duplicate submissions with the same chatbot, name, and phone number within 15 seconds are deduplicated automatically and return the existing lead record.

<Tip>
  Connect lead capture to Zapier to automatically add new leads to your CRM, email list, or any other tool in your stack. See [Zapier Integration](/integrations/zapier) to get started.
</Tip>