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://service.tailortalk.ai/api/v1/get_leads

Headers

Key Value
Authorization Agent <token>

You can find agent_token in Manage Agent page.

text

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")
limit ❌ Number of leads to retrieve (max 100)

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
}

Response Format

The API returns a JSON object with lead information:

{
    "data": {
        "leads": [
            {
                "lead_name": "shivajbd@gmail.com",
                "lead_contact": "91********",
                "lead_status": "cold",
                "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": "warm",
                "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
}

Notes

  • Ensure that the agent access token is included in the request headers
  • Maximum limit per request is 100 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
XLinkedIn