Events for a Lead API

Retrieve all engagement events for a specific lead, ordered by most recent first.

GET /events/{leadID}

List events for a specific lead.

Request

Parameter	Type	Required	Description
leadID	string	Yes	Lead identifier (path parameter)
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page (default: 25, max: 100)
event_type	string	No	Filter by event type

Response

200 OK

{
  "events": [
    {
      "id": "evt-123",
      "lead_id": "ld_456",
      "event_type": "Page View",
      "metadata": {
        "path": "/pricing",
        "referrer": "https://google.com"
      },
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 25
}

Example

curl -X GET "https://api.kenbun.io/events/ld_456?page=1&limit=25" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
404	Not Found	Lead does not exist or not accessible

---

Notes

• Events are returned in reverse chronological order (most recent first)
• Results are OU-scoped to the active Organizational Unit
• When leads are merged, events from the absorbed lead(s) are moved to this lead. Moved events include an original_lead_id field indicating which lead originally owned the event.
• A lead_merged event type appears in the timeline when this lead absorbed another lead during a merge. Its metadata includes the source lead IDs, how many events were moved, and who performed the merge.

Related Endpoints

• Events - List all events
• Lead Detail - View lead details
• Score Explain - Understand lead's score drivers
• Lead Merge - Merge duplicate leads and view merge history