Docs/API/Leads

Leads API

Retrieve and manage leads captured by your chatbots.

List Leads

GET/v1/leads
curl -X GET "https://api.chatmefy.com/v1/leads?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "lead_abc123",
      "email": "john@company.com",
      "name": "John Smith",
      "phone": "+1234567890",
      "company": "Acme Corp",
      "score": 85,
      "source": {
        "url": "/pricing",
        "campaign": "google_ads"
      },
      "custom_fields": {
        "company_size": "51-200",
        "budget": "$10k-50k"
      },
      "conversation_id": "conv_xyz",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 1523,
    "page": 1,
    "per_page": 20
  }
}

Query Parameters

limitResults per page (1-100, default 20)
pagePage number
score_minMinimum lead score
score_maxMaximum lead score
bot_idFilter by bot
sinceCreated after date (ISO8601)
untilCreated before date (ISO8601)

Get Single Lead

GET/v1/leads/:id
curl -X GET "https://api.chatmefy.com/v1/leads/lead_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Update Lead

PATCH/v1/leads/:id
curl -X PATCH "https://api.chatmefy.com/v1/leads/lead_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John D. Smith",
    "custom_fields": {
      "status": "contacted"
    }
  }'

Delete Lead

DELETE/v1/leads/:id
curl -X DELETE "https://api.chatmefy.com/v1/leads/lead_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": {
    "id": "lead_abc123",
    "deleted": true
  }
}

Lead Object

FieldTypeDescription
idstringUnique lead identifier
emailstringContact email
namestringFull name
phonestringPhone number
companystringCompany name
scoreintegerLead score (0-100)
sourceobjectURL, referrer, campaign
custom_fieldsobjectYour custom field data
conversation_idstringRelated conversation
created_atISO8601When lead was captured