Get Leads API

The Get Leads API allows you to retrieve leads that are talking to your AI agent. You can filter leads by status and time period, making it easy to integrate with your CRM or other systems.

API Endpoint

https://api.tailortalk.ai/api/v1/get_leads

Headers

Key	Value
Authorization	Agent <token>

You can find agent_token on the Developer page, under the API Keys tab. Click the eye icon to reveal it, or the copy icon to copy it.

Request Body

Parameter	Required	Description
start_after	❌	ISO 8601 timestamp - Get leads who messaged before this date (used for pagination)
lead_status	❌	Filter by lead status (e.g., "cold", "warm", "hot" for sales leads, "open" or "resolved" for support)
lead_source	❌	Filter by lead source (e.g., "whatsappdm", "instagramdm", "web_chat")
limit	❌	Number of leads to retrieve (max 200)

Example: Basic Request

{
    "start_after": "2026-08-03T17:30:05+00:00",
    "lead_status": "cold",
    "limit": 2
}

Example: Pagination

To paginate through leads, use the last_message_time from the last lead in the previous response as start_after in the next request:

{
    "start_after": "2025-11-08T05:39:17+00:00",
    "limit": 50
}

This will fetch the next 50 leads who messaged before 2025-11-08T05:39:17+00:00.

Example: Get All Recent Leads

{
    "limit": 50
}

Example: Get Hot Leads

{
    "lead_status": "hot",
    "limit": 100
}

Example: Get Leads from WhatsApp

{
    "lead_source": "whatsapp_dm",
    "limit": 50
}

Response Format

The API returns a JSON object with lead information:

{
    "data": {
        "leads": [
            {
                "lead_name": "shivajbd@gmail.com",
                "lead_contact": "91********",
                "lead_status": "cold",
                "category": "sales",
                "is_converted": false,
                "converted_at": null,
                "last_message_time": "2025-11-08T05:39:17+00:00",
                "joined": "2025-11-08T05:38:38+00:00",
                "total_followups": 0,
                "integration": "assistant",
                "id": "zrpxkxxu_assistant_shivajbdgmailcom"
            },
            {
                "lead_name": "akshatofficial007@gmail.com",
                "lead_contact": "91********",
                "lead_status": "open",
                "category": "support",
                "is_converted": true,
                "converted_at": "2025-09-14T11:02:44+00:00",
                "last_message_time": "2025-10-23T10:26:29+00:00",
                "joined": "2025-10-23T10:26:29+00:00",
                "total_followups": 0,
                "integration": "assistant",
                "id": "zrpxkxxu_assistant_akshatofficial007gmailcom"
            }
        ],
        "count": 2
    },
    "success": true
}

Categories and conversion

Each lead carries a category alongside its status, set by your agent from the conversation:

Field	Meaning
category	sales, support or others — what the lead is doing now. It changes as the conversation does, so a customer who buys and later asks about delivery moves from sales to support.
lead_status	Depends on the category: your configured sales statuses, open/resolved for support, or a short label your agent writes for others (always spam when it is spam).
is_converted	true once the lead has bought, and it stays true. Use this rather than lead_status == "converted" to count customers — a converted customer asking a support question no longer carries that status.
converted_at	When they first converted, or null.

The second example above shows why the two differ: that lead has an open support question and has already bought.

Notes

• Ensure that the agent access token is included in the request headers
• Maximum limit per request is 200 leads
• Pagination: Use the last_message_time from the last lead in the response as start_after in your next request to fetch older leads
• All dates should be in ISO 8601 format with timezone (e.g., 2025-11-08T05:39:17+00:00)
• If no parameters are provided, recent leads will be returned
• The response includes only the most important fields - additional fields may be present but can be omitted for basic usage