Leads API Endpoints for Managing Captured Contacts

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.

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.

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:

string

required

The unique ID of the agent whose widget the lead was captured through.

Request body:

string

required

The contact’s full name.

string

required

The contact’s phone number in any format (e.g., "+1-555-0100", "07911 123456").

Response (200 OK):

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

string

Unique identifier for the captured lead.

string

The agent ID the lead was captured through.

string

The contact’s name as submitted.

string

The contact’s phone number as submitted.

string

ISO 8601 timestamp of when the lead was captured.

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.

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/chatbot-leads/CHATBOT_ID

Path parameters:

string

required

The unique ID of the agent whose widget leads you want to list.

Response (200 OK):

[
  {
    "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.

curl -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/leads

Response (200 OK):

[
  {
    "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"
  }
]

string

Unique identifier for the lead.

string

The ID of the account that owns this lead.

string

The contact’s name.

string

Contact information — typically an email address or phone number.

string

Lead status: "New", "Contacted", or "Closed".

string | null

Optional free-text notes about the lead.

string

ISO 8601 timestamp of when the lead was created.

string

ISO 8601 timestamp of the last update to the lead.

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.

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:

string

required

The contact’s full name.

string

required

Contact information for the lead — typically an email address or phone number.

string

Optional free-text notes about the lead (e.g., source, interest, context).

string

Initial status for the lead. One of: "New" (default), "Contacted", "Closed".

Response (200 OK):

{
  "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.

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:

string

required

The unique ID of the lead to update.

Request body (all optional):

string

Updated contact name.

string

Updated contact information.

string

Updated lead status: "New", "Contacted", or "Closed".

string

Updated notes.

Response (200 OK): The updated lead object (same structure as 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.

curl -X DELETE \
  -H "Authorization: Bearer TOKEN" \
  https://app.botsmith.ai/api/leads/LEAD_ID

Path parameters:

string

required

The unique ID of the lead to delete.

Response (200 OK):

{
  "success": true,
  "message": "Lead deleted successfully",
  "lead_id": "lead_ghi789"
}

boolean

true when the lead was successfully deleted.

string

Human-readable confirmation message.

string

The ID of the lead that was deleted.

Overview

Endpoints

Leads API Endpoints for Managing Captured Contacts

Public: Capture a Widget Lead

List Widget Leads for an Agent

List Account Leads

Create an Account Lead

Update an Account Lead

Delete an Account Lead

​Public: Capture a Widget Lead

​List Widget Leads for an Agent

​List Account Leads

​Create an Account Lead

​Update an Account Lead

​Delete an Account Lead

Public: Capture a Widget Lead

List Widget Leads for an Agent

List Account Leads

Create an Account Lead

Update an Account Lead

Delete an Account Lead