API Overview

The Leezy API provides programmatic access to your chatbot data, leads, tickets, and meetings. Use it to integrate Leezy with your existing tools and workflows.

Base URL

https://app.leezy.ai/api/v1

Requirements

Paid Plan Required

API access requires a Starter plan or higher. Free tier users cannot access the API.

Authentication

All API requests require authentication using a Bearer token in the Authorization header:

curl -X GET "https://app.leezy.ai/api/v1/leads" \
  -H "Authorization: Bearer lzy_at_your_access_token"

Access tokens are obtained through OAuth 2.0 authentication.

Response Format

All responses follow a consistent JSON structure:

Success Response

{
  "data": [
    {
      "id": "abc123",
      "type": "lead",
      "attributes": {
        "contact": {
          "name": "John Doe",
          "email": "john@example.com"
        },
        "created_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "api_version": "2024-01-01",
    "total": 42,
    "limit": 20,
    "offset": 0,
    "has_more": true,
    "count": 20
  }
}

Error Response

{
  "error": "invalid_token",
  "error_description": "The access token is invalid or has expired"
}

Pagination

List endpoints support pagination with limit and offset parameters:

Parameter	Type	Default	Max	Description
limit	integer	20	100	Number of records to return
offset	integer	0	-	Number of records to skip

# Get page 2 with 50 items per page
GET /api/v1/leads?limit=50&offset=50

Filtering

Most endpoints support filtering:

# Filter leads by chatbot
GET /api/v1/leads?chatbot_id=abc123

# Filter by status
GET /api/v1/tickets?status=open

# Polling: Get records updated since timestamp
GET /api/v1/leads?since=2024-01-15T10:00:00Z

Rate Limits

Plan	Rate Limit
Starter	100 requests/minute
Pro	300 requests/minute
Business	1,000 requests/minute

When rate limited, you receive a 429 Too Many Requests response:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Please retry after 60 seconds."
}

Error Codes

Status Code	Error	Description
400	invalid_request	Request validation failed
401	unauthorized	Missing or invalid Authorization header
401	invalid_token	Access token expired or invalid
403	insufficient_scope	Token lacks required scope
403	plan_required	Paid plan required for API access
404	not_found	Resource does not exist
429	rate_limit_exceeded	Too many requests
500	server_error	Internal server error

Available Endpoints

Endpoint	Methods	Scope Required
/api/v1/chatbots	GET	-
/api/v1/leads	GET	leads:read
/api/v1/tickets	GET	tickets:read
/api/v1/meetings	GET	meetings:read
/api/v1/webhooks	GET, POST, DELETE	webhooks:manage

Next Steps

• Authentication - Learn about OAuth 2.0 setup
• Webhooks - Real-time event notifications
• Zapier Integration - Connect without code