Skip to main content

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​

ParameterTypeRequiredDescription
pageintegerNoPage number (default: 1)
limitintegerNoResults per page (default: 25)
min_scoreintegerNoMinimum total engagement score
max_scoreintegerNoMaximum total engagement score
event_typestringNoFilter by last event type
last_activestringNoFilter by recency: 7d or 30d
rangestringNoFilter 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​

FieldTypeDescription
leadsarrayArray of lead objects
leads[].org_idstringOrganization identifier
leads[].lead_idstringLead identifier
leads[].scoreintegerOverall engagement score (used for level derivation)
leads[].ruleset_idstringLast-joined engagement ruleset ID (may be empty if no engagement score yet)
leads[].last_event_attimestamp or nullTimestamp of the lead's most recent event
leads[].created_attimestampWhen the lead was created
leads[].updated_attimestampWhen the lead was last updated
leads[].owner_namestring or nullName of the assigned owner
leads[].engagement_scoresobjectMap of engagement ruleset ID to score
leads[].profile_scoresobjectMap of profile ruleset ID to score
leads[].ruleset_namesobjectMap of ruleset ID to human-readable name (both engagement and profile)
leads[].engagement_primary_ruleset_namestringPrimary engagement ruleset name for this OU
leads[].profile_primary_ruleset_namestringPrimary profile ruleset name for this OU
totalintegerTotal number of leads matching filters (paginated response only)
pageintegerCurrent page number (paginated response only)
limitintegerResults per page (paginated response only)

Examples​

List leads with pagination:

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

Filter by minimum score and recency:

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

Filter by event type:

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

Common Errors​

StatusMeaningSolution
401UnauthorizedCheck 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