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

# Leads API Endpoints for Managing Captured Contacts

> Retrieve, create, update, and delete leads captured by your BotSmith chat widget or added manually using the Leads REST API endpoints.

The Leads API lets you retrieve and manage the contacts captured by your BotSmith widget's lead form. Use it to sync leads with your CRM, export them to other systems, or create leads manually from your own application.

BotSmith has two types of leads:

* **Widget leads** — contacts captured through an agent's embedded chat widget lead form (`name` + `phone`). Stored against a specific agent. No authentication required to submit.
* **Account leads** — contacts you manage directly in your BotSmith account (`name` + `contact` + `notes` + `status`). Used for your own CRM-style tracking. Requires authentication.

***

## Public: Capture a Widget Lead

**`POST /api/public/lead/{chatbot_id}`**

Submits a lead captured through an agent's widget lead form. No authentication required — this endpoint is called by the embedded widget on your visitors' behalf.

BotSmith deduplicates rapid submissions: if the same name and phone number are submitted for the same agent within 15 seconds, the existing lead record is returned instead of creating a duplicate.

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

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent whose widget the lead was captured through.
</ParamField>

**Request body:**

<ParamField body="name" type="string" required>
  The contact's full name.
</ParamField>

<ParamField body="phone" type="string" required>
  The contact's phone number in any format (e.g., `"+1-555-0100"`, `"07911 123456"`).
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "id": "lead_abc123",
  "chatbot_id": "bot_abc123",
  "name": "Jane Smith",
  "phone": "+1-555-0100",
  "created_at": "2024-06-01T10:00:00Z"
}
```

<ResponseField name="id" type="string">
  Unique identifier for the captured lead.
</ResponseField>

<ResponseField name="chatbot_id" type="string">
  The agent ID the lead was captured through.
</ResponseField>

<ResponseField name="name" type="string">
  The contact's name as submitted.
</ResponseField>

<ResponseField name="phone" type="string">
  The contact's phone number as submitted.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the lead was captured.
</ResponseField>

***

## List Widget Leads for an Agent

**`GET /api/chatbot-leads/{chatbot_id}`**

Returns all leads captured through a specific agent's widget, sorted by most recent first. Requires authentication — you can only access leads for agents that belong to your account.

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

**Path parameters:**

<ParamField path="chatbot_id" type="string" required>
  The unique ID of the agent whose widget leads you want to list.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
[
  {
    "id": "lead_abc123",
    "chatbot_id": "bot_abc123",
    "name": "Jane Smith",
    "phone": "+1-555-0100",
    "created_at": "2024-06-01T10:00:00Z"
  },
  {
    "id": "lead_def456",
    "chatbot_id": "bot_abc123",
    "name": "John Doe",
    "phone": "+1-555-0199",
    "created_at": "2024-06-01T11:30:00Z"
  }
]
```

***

## List Account Leads

**`GET /api/leads`**

Returns all account-level leads belonging to the authenticated user.

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

**Response (`200 OK`):**

```json theme={null}
[
  {
    "id": "lead_ghi789",
    "user_id": "user_abc123",
    "name": "Alice Johnson",
    "contact": "alice@example.com",
    "status": "New",
    "notes": "Interested in the Pro plan",
    "created_at": "2024-06-01T08:00:00Z",
    "updated_at": "2024-06-01T08:00:00Z"
  }
]
```

<ResponseField name="id" type="string">
  Unique identifier for the lead.
</ResponseField>

<ResponseField name="user_id" type="string">
  The ID of the account that owns this lead.
</ResponseField>

<ResponseField name="name" type="string">
  The contact's name.
</ResponseField>

<ResponseField name="contact" type="string">
  Contact information — typically an email address or phone number.
</ResponseField>

<ResponseField name="status" type="string">
  Lead status: `"New"`, `"Contacted"`, or `"Closed"`.
</ResponseField>

<ResponseField name="notes" type="string | null">
  Optional free-text notes about the lead.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the lead was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the last update to the lead.
</ResponseField>

***

## Create an Account Lead

**`POST /api/leads`**

Manually creates a new account-level lead. Your plan determines how many leads you can store — a `403` response means you have reached your limit.

```bash theme={null}
curl -X POST https://app.botsmith.ai/api/leads \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Johnson",
    "contact": "alice@example.com",
    "notes": "Interested in the Pro plan"
  }'
```

**Request body:**

<ParamField body="name" type="string" required>
  The contact's full name.
</ParamField>

<ParamField body="contact" type="string" required>
  Contact information for the lead — typically an email address or phone number.
</ParamField>

<ParamField body="notes" type="string">
  Optional free-text notes about the lead (e.g., source, interest, context).
</ParamField>

<ParamField body="status" type="string">
  Initial status for the lead. One of: `"New"` (default), `"Contacted"`, `"Closed"`.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "id": "lead_ghi789",
  "user_id": "user_abc123",
  "name": "Alice Johnson",
  "contact": "alice@example.com",
  "status": "New",
  "notes": "Interested in the Pro plan",
  "created_at": "2024-06-01T08:00:00Z",
  "updated_at": "2024-06-01T08:00:00Z"
}
```

***

## Update an Account Lead

**`PUT /api/leads/{lead_id}`**

Updates one or more fields on an existing account-level lead. Only include the fields you want to change.

```bash theme={null}
curl -X PUT https://app.botsmith.ai/api/leads/LEAD_ID \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "Contacted",
    "notes": "Called on 2024-06-02, interested in annual plan"
  }'
```

**Path parameters:**

<ParamField path="lead_id" type="string" required>
  The unique ID of the lead to update.
</ParamField>

**Request body (all optional):**

<ParamField body="name" type="string">
  Updated contact name.
</ParamField>

<ParamField body="contact" type="string">
  Updated contact information.
</ParamField>

<ParamField body="status" type="string">
  Updated lead status: `"New"`, `"Contacted"`, or `"Closed"`.
</ParamField>

<ParamField body="notes" type="string">
  Updated notes.
</ParamField>

**Response (`200 OK`):** The updated lead object (same structure as [List Account Leads](#list-account-leads)).

***

## Delete an Account Lead

**`DELETE /api/leads/{lead_id}`**

Permanently deletes an account-level lead. Returns a confirmation object on success. You can only delete leads that belong to your account.

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

**Path parameters:**

<ParamField path="lead_id" type="string" required>
  The unique ID of the lead to delete.
</ParamField>

**Response (`200 OK`):**

```json theme={null}
{
  "success": true,
  "message": "Lead deleted successfully",
  "lead_id": "lead_ghi789"
}
```

<ResponseField name="success" type="boolean">
  `true` when the lead was successfully deleted.
</ResponseField>

<ResponseField name="message" type="string">
  Human-readable confirmation message.
</ResponseField>

<ResponseField name="lead_id" type="string">
  The ID of the lead that was deleted.
</ResponseField>