New API Endpoint: Attach Lead & Enhanced Customer Filtering
Samuel Su
on October 7, 2025We've released two API enhancements to improve lead management and customer data integration.
New Endpoint: POST /attach-lead
Attach or update lead information for a specific conversation.
Request Example:
POST /api/v2/attach-lead Authorization: Bearer YOUR_API_KEY Content-Type: application/json { "conversationId": "conv_123456", "chatbotId": "chatbot_789", "email": "[email protected]", "phone": "+1234567890", "name": "John Doe" }
Response:
{ "status": "success", "lead": { "leadId": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", "email": "[email protected]", "phone": "+1234567890", "source": "api" } }
Common Use Cases:
- Sync customer data from your CRM (Salesforce, HubSpot, etc.) to Chat Data conversations
- Update lead information after purchases, form submissions, or user actions
- Link conversations across channels (web, WhatsApp, Messenger) to the same customer record
Key Features:
- Searches for existing leads using all provided fields (best-effort matching)
- Creates new leads automatically if no match is found
- UUID cannot be changed once a lead exists
- Supports fields: email, phone, name, psid, ig_username, username, uuid
Enhanced: GET /get-customers
The /get-customers endpoint now supports filtering and includes leadId in responses.
New Query Parameters:
- leadId - Filter by lead identifier
- email - Filter by email address
- phone - Filter by phone number
- name - Filter by customer name
- psid - Filter by Page Scoped User ID
- ig_username - Filter by Instagram username
- username - Filter by username
Example Request:
GET /api/v2/get-customers/chatbot_789?email=[email protected] Authorization: Bearer YOUR_API_KEY
Example Response:
{ "status": "success", "customers": [ { "leadId": "550e8400-e29b-41d4-a716-446655440000", "name": "John Doe", "email": "[email protected]", "phone": "+1234567890", "source": "widget", "createdAt": 1696118400000 } ], "total": 1 }
Common Use Cases:
- Look up specific customers by email or phone number
- Filter customers by source and other attributes for reporting
- Use leadId to cross-reference customers across different API endpoints
Getting Started
Step 1: Get your API key from Account Settings → API Keys or Chatbot Settings → API Keys
Step 2: Try the endpoints
# Attach a lead to a conversation curl -X POST https://api.chat-data.com/api/v2/attach-lead \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "conversationId": "your_conversation_id", "chatbotId": "your_chatbot_id", "email": "[email protected]", "name": "John Doe" }' # Filter customers by email curl -X GET "https://api.chat-data.com/api/v2/get-customers/[email protected]" \ -H "Authorization: Bearer YOUR_API_KEY"
Documentation
For complete API specifications, request/response schemas, and error handling details, see:
Available now for all plans with API access. See PR #1281 for technical implementation details.