Skip to main content

Leads API

Retrieve qualified leads captured by your chatbots using BANT methodology (Budget, Authority, Need, Timeline).

List Leads​

GET /api/v1/leads

Required Scope: leads:read

Query Parameters​

ParameterTypeDefaultDescription
limitinteger20Number of records (1-100)
offsetinteger0Number of records to skip
chatbot_idUUID-Filter by chatbot
statusstring-Filter by status (new, contacted, qualified, converted, lost)
qualifiedboolean-Filter by qualification status
sinceISO 8601-Get leads updated after timestamp (for polling)

Example Request​

curl -X GET "https://app.leezy.ai/api/v1/leads?chatbot_id=abc123&limit=10" \
-H "Authorization: Bearer lzy_at_your_token"

Response​

{
"data": [
{
"id": "lead_abc123",
"type": "lead",
"attributes": {
"chatbot_id": "chatbot_xyz789",
"conversation_id": "conv_def456",
"contact": {
"name": "Sarah Johnson",
"email": "sarah@acme.com",
"phone": "+1-555-0123",
"company": "Acme Corp"
},
"qualification": {
"score": 85,
"qualified": true,
"recommendation": "High-priority lead. Schedule demo within 48 hours.",
"budget": "50,000-100,000 EUR",
"authority": "Decision maker - VP of Sales",
"need": "Looking to automate customer support",
"timeline": "Q1 2025"
},
"key_pain_points": [
"High support ticket volume",
"Slow response times",
"Limited 24/7 coverage"
],
"conversation_summary": "Discussed AI chatbot implementation for customer support. Interested in enterprise features.",
"status": "new",
"notes": null,
"assigned_to": null,
"follow_up_date": "2024-01-20",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
],
"meta": {
"api_version": "2024-01-01",
"total": 42,
"limit": 10,
"offset": 0,
"has_more": true,
"count": 10
}
}

Lead Object​

FieldTypeDescription
idstringUnique lead identifier
chatbot_idUUIDChatbot that captured the lead
conversation_idUUIDSource conversation
contact.namestringContact name
contact.emailstringContact email
contact.phonestringContact phone
contact.companystringCompany name
qualification.scoreintegerBANT score (0-100)
qualification.qualifiedbooleanWhether lead is qualified
qualification.recommendationstringAI recommendation
qualification.budgetstringBudget information
qualification.authoritystringDecision-making authority
qualification.needstringIdentified needs
qualification.timelinestringPurchase timeline
key_pain_pointsarrayList of identified pain points
conversation_summarystringAI-generated conversation summary
statusstringLead status
notesstringManual notes
assigned_tostringAssigned team member email
follow_up_datestringSuggested follow-up date
created_atISO 8601Creation timestamp
updated_atISO 8601Last update timestamp

Status Values​

StatusDescription
newNewly captured lead
contactedInitial contact made
qualifiedConfirmed qualified
convertedBecame customer
lostLead lost

Polling for New Leads​

Use the since parameter to poll for new or updated leads:

# Get leads updated in the last hour
GET /api/v1/leads?since=2024-01-15T09:30:00Z

This is useful when building real-time integrations without webhooks.

Error Responses​

StatusErrorDescription
401unauthorizedMissing or invalid token
403insufficient_scopeToken lacks leads:read scope
403plan_requiredPaid plan required

Next Steps​