Documentation/API Reference/Lead Capture

Lead Capture API

API endpoint for capturing and storing leads from the chat widget.

POST
/api/lead

Captures lead information and stores it in the database. Optionally triggers a webhook if configured for the client.

Request

Request Body
JSON payload with lead information
FieldTypeRequiredDescription
clientId
string
Required
UUID of the client
name
string
Required
Lead's full name
email
string
Required
Lead's email address
phone
string
Optional
Lead's phone number
message
string
Optional
Additional details or message

Example

cURL Request
curl -X POST https://sensei-ai-eight.vercel.app/api/lead \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "d454991a-eddb-4e81-959d-87c868e050ca",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "message": "I need a quote for enterprise plan"
  }'

Response

200
Success
{
  "success": true,
  "leadId": "abc123-def456-ghi789",
  "message": "Lead captured successfully"
}
400
Bad Request
{
  "error": "Missing required fields",
  "details": ["clientId is required", "email is required"]
}

Webhook Trigger

Automatic Webhook
If a webhook URL is configured in client settings, it will be called automatically

When a lead is captured and the client has a webhook URL configured, the API will send a POST request to that URL with the lead data:

POST https://client-webhook.example.com/leads
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "phone": "+1234567890",
  "message": "I need a quote for enterprise plan",
  "clientId": "d454991a-eddb-4e81-959d-87c868e050ca",
  "timestamp": "2024-11-24T10:30:00.000Z"
}