Top Leads API

Retrieve leads with the highest scores for the active Organizational Unit. Useful for dashboards and sales prioritization.

GET /top-leads

Get the top-scoring leads.

Request

Parameter	Type	Required	Description
limit	integer	No	Maximum number of results (default: 10)

Response

200 OK

{
  "leads": [
    {
      "lead_id": "ld_123",
      "score": 120,
      "last_event_at": "2025-01-15T10:30:00Z"
    },
    {
      "lead_id": "ld_456",
      "score": 95,
      "last_event_at": "2025-01-15T09:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
lead_id	string	Lead identifier
score	integer	Current engagement score
last_event_at	timestamp	Most recent event for the lead

Example

curl -X GET "https://api.leadvibe.com/top-leads?limit=10" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token
500	Server Error	Contact support if persists

---

Notes

• Results are OU-scoped to the active Organizational Unit
• Leads are ordered by engagement score, highest first

Related Endpoints

• Score Gains - Leads with fastest-rising scores
• Leads - Full lead listing with filters