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

Parameter	Type	Default	Description
limit	integer	20	Number of records (1-100)
offset	integer	0	Number of records to skip
chatbot_id	UUID	-	Filter by chatbot
status	string	-	Filter by status (new, contacted, qualified, converted, lost)
qualified	boolean	-	Filter by qualification status
since	ISO 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

Field	Type	Description
id	string	Unique lead identifier
chatbot_id	UUID	Chatbot that captured the lead
conversation_id	UUID	Source conversation
contact.name	string	Contact name
contact.email	string	Contact email
contact.phone	string	Contact phone
contact.company	string	Company name
qualification.score	integer	BANT score (0-100)
qualification.qualified	boolean	Whether lead is qualified
qualification.recommendation	string	AI recommendation
qualification.budget	string	Budget information
qualification.authority	string	Decision-making authority
qualification.need	string	Identified needs
qualification.timeline	string	Purchase timeline
key_pain_points	array	List of identified pain points
conversation_summary	string	AI-generated conversation summary
status	string	Lead status
notes	string	Manual notes
assigned_to	string	Assigned team member email
follow_up_date	string	Suggested follow-up date
created_at	ISO 8601	Creation timestamp
updated_at	ISO 8601	Last update timestamp

Status Values

Status	Description
new	Newly captured lead
contacted	Initial contact made
qualified	Confirmed qualified
converted	Became customer
lost	Lead 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

Status	Error	Description
401	unauthorized	Missing or invalid token
403	insufficient_scope	Token lacks leads:read scope
403	plan_required	Paid plan required

Next Steps

• Webhooks - Get real-time lead.created events
• Zapier Integration - Send leads to your CRM