v1.0 • Lead Management
Add a new lead to your workspace
Create a new lead with the provided information
POST ${baseUrl}/api/v1/chatbots/{chatbotId}/leadschatbotIdThe unique identifier of the chatbot to create the lead for (required)
JSON payload with lead information
{
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1-555-123-4567",
"source": "website",
"status": "new",
"metadata": {
"utm_source": "google",
"utm_campaign": "spring_2024",
"interests": ["product_a", "product_b"],
"company": "Tech Corp",
"job_title": "Marketing Manager"
}
}nameLead's full name
emailValid email address
phonePhone number
sourceLead source
statusLead status
metadataCustom data
The metadata field can store any custom JSON data. Common uses include UTM parameters, company information, lead scoring, or integration-specific data.
Successful creation returns the new lead with generated ID
{
"success": true,
"data": {
"id": "lead_1234567890abcdef",
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1-555-123-4567",
"source": "website",
"status": "new",
"metadata": {
"utm_source": "google",
"utm_campaign": "spring_2024",
"interests": ["product_a", "product_b"],
"company": "Tech Corp",
"job_title": "Marketing Manager"
},
"createdAt": "2024-01-15T10:30:00.000Z",
"updatedAt": "2024-01-15T10:30:00.000Z",
"workspaceId": "ws_your_workspace_id"
}
}idUnique lead identifier (auto-generated)
createdAtISO timestamp of creation
updatedAtISO timestamp of last update
workspaceIdYour workspace identifier
Implementation examples in different languages
curl -X POST https://your-domain.com/api/v1/chatbots/cb_1234567890abcdef/leads \
-H "Authorization: Bearer sk-workspace_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1-555-123-4567",
"source": "website",
"status": "new",
"metadata": {
"utm_source": "google",
"company": "Tech Corp"
}
}'const createLead = async (leadData) => {
try {
const response = await fetch('https://your-domain.com/api/v1/leads', {
method: 'POST',
headers: {
'Authorization': 'Bearer sk-workspace_your_api_key',
'Content-Type': 'application/json'
},
body: JSON.stringify(leadData)
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
return result.data;
} catch (error) {
console.error('Error creating lead:', error);
throw error;
}
};
// Usage
const newLead = {
name: "John Doe",
email: "john.doe@example.com",
phone: "+1-555-123-4567",
source: "website",
status: "new",
metadata: {
utm_source: "google",
company: "Tech Corp"
}
};
createLead(newLead);import requests
import json
def create_lead(api_key, lead_data):
url = "https://your-domain.com/api/v1/leads"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
try:
response = requests.post(url, headers=headers, json=lead_data)
response.raise_for_status() # Raises an HTTPError for bad responses
result = response.json()
print(f"Lead created: {result['data']['id']}")
return result['data']
except requests.exceptions.RequestException as e:
print(f"Error creating lead: {e}")
raise
# Usage
api_key = "sk-workspace_your_api_key"
new_lead = {
"name": "John Doe",
"email": "john.doe@example.com",
"phone": "+1-555-123-4567",
"source": "website",
"status": "new",
"metadata": {
"utm_source": "google",
"company": "Tech Corp"
}
}
create_lead(api_key, new_lead)Handle these error scenarios in your implementation
{
"success": false,
"error": "Validation failed",
"code": "VALIDATION_ERROR",
"details": {
"field": "email",
"value": "invalid-email",
"message": "Must be a valid email address"
}
}{
"success": false,
"error": "Email already exists",
"code": "DUPLICATE_EMAIL",
"details": {
"email": "john.doe@example.com",
"existingLeadId": "lead_existing123",
"message": "A lead with this email already exists in your workspace"
}
}