Leads API

Retrieve lead scores for the active Organizational Unit with pagination, filtering, and multi-ruleset score breakdowns.

GET /leads

List leads with their scores, ruleset breakdowns, and metadata. When multiple scoring rulesets exist, per-ruleset score maps are included so you can display score tooltips and legends in your UI.

Request

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Results per page (default: 25)
min_score	integer	No	Minimum total engagement score
max_score	integer	No	Maximum total engagement score
event_type	string	No	Filter by last event type
last_active	string	No	Filter by recency: 7d or 30d
range	string	No	Filter by lead created date: today, yesterday, last_7d, last_30d, last_90d

Response

200 OK

When page or limit is provided, the response includes pagination metadata.

{
  "leads": [
    {
      "org_id": "org_123",
      "lead_id": "lead_A",
      "score": 40,
      "ruleset_id": "11111111-1111-1111-1111-111111111111",
      "last_event_at": "2025-09-04T19:20:30Z",
      "created_at": "2025-09-01T12:00:00Z",
      "updated_at": "2025-09-04T19:20:30Z",
      "owner_name": "Ada Lovelace",
      "engagement_scores": {
        "11111111-1111-1111-1111-111111111111": 40,
        "22222222-2222-2222-2222-222222222222": 35
      },
      "profile_scores": {
        "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaa1": 10
      },
      "ruleset_names": {
        "11111111-1111-1111-1111-111111111111": "Engagement - Standard",
        "22222222-2222-2222-2222-222222222222": "Engagement - Experimental",
        "aaaaaaa1-aaaa-aaaa-aaaa-aaaaaaaaaaa1": "Profile - Fit A"
      },
      "engagement_primary_ruleset_name": "Engagement - Standard",
      "profile_primary_ruleset_name": "Profile - Fit A"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 25
}

Response Fields

Field	Type	Description
leads	array	Array of lead objects
leads[].org_id	string	Organization identifier
leads[].lead_id	string	Lead identifier
leads[].score	integer	Overall engagement score (used for level derivation)
leads[].ruleset_id	string	Last-joined engagement ruleset ID (may be empty if no engagement score yet)
leads[].last_event_at	timestamp or null	Timestamp of the lead's most recent event
leads[].created_at	timestamp	When the lead was created
leads[].updated_at	timestamp	When the lead was last updated
leads[].owner_name	string or null	Name of the assigned owner
leads[].engagement_scores	object	Map of engagement ruleset ID to score
leads[].profile_scores	object	Map of profile ruleset ID to score
leads[].ruleset_names	object	Map of ruleset ID to human-readable name (both engagement and profile)
leads[].engagement_primary_ruleset_name	string	Primary engagement ruleset name for this OU
leads[].profile_primary_ruleset_name	string	Primary profile ruleset name for this OU
total	integer	Total number of leads matching filters (paginated response only)
page	integer	Current page number (paginated response only)
limit	integer	Results per page (paginated response only)

Examples

List leads with pagination:

curl -X GET "https://api.leadvibe.com/leads?page=1&limit=25" \
  -H "Authorization: Bearer <token>"

Filter by minimum score and recency:

curl -X GET "https://api.leadvibe.com/leads?min_score=50&last_active=30d" \
  -H "Authorization: Bearer <token>"

Filter by event type:

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

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication credentials

---

Notes

• Results are OU-scoped to the active Organizational Unit
• Leads are included even if they have no scored events yet
• When multiple rulesets exist, engagement_scores and profile_scores provide per-ruleset breakdowns
• The ruleset_names map lets you display human-readable names for each ruleset ID
• Without pagination parameters, the response returns all matching leads as an array

Related Endpoints

• Lead by ID - Get, update, or delete a single lead
• Lead Search - Full-text search for leads
• Score - Get detailed score breakdown for a lead
• Top Leads - Get highest-scoring leads