Skip to main content

Score Explanation API

Get a concise explanation of what is driving a lead's score within a recent time window. This endpoint surfaces the top scoring factors, current rule weights, and any decay applied, helping your team understand why a lead has a particular score.

GET /lead/{leadID}/score-explain​

Returns score drivers, a snapshot of active rule weights, and total decay applied within the specified time window.

Request​

ParameterTypeRequiredDescription
leadIDstringYesLead identifier (path parameter)
hoursintegerNoTime window in hours (default: 24)

Response​

200 OK

{
  "top_drivers": [
    {
      "rule_id": "rl_abc123",
      "event_type": "page_view",
      "count": 4,
      "weight": 10,
      "total": 40,
      "filter_label": "path contains /pricing"
    },
    {
      "rule_id": "rl_def456",
      "event_type": "page_view",
      "count": 7,
      "weight": 5,
      "total": 35
    },
    {
      "rule_id": "rl_ghi789",
      "event_type": "email_click",
      "count": 3,
      "weight": 5,
      "total": 15
    }
  ],
  "snapshot": [
    { "event_type": "page_view", "weight": 10 },
    { "event_type": "email_click", "weight": 5 }
  ],
  "decay_applied": -6,
  "inorganic_count": 0,
  "range_hours": 24,
  "score_reset_at": null,
  "reset_excluded_count": 0
}

Response Fields​

FieldTypeDescription
top_driversarrayScoring rules that contributed to the lead's score in the window, sorted by absolute contribution (highest first)
top_drivers[].rule_idstringUnique identifier of the scoring rule
top_drivers[].event_typestringEvent type this rule scores
top_drivers[].countintegerNumber of events attributed to this rule in the window
top_drivers[].weightintegerPoint value of the rule
top_drivers[].totalintegerTotal points contributed by this rule (count × weight)
top_drivers[].filter_labelstringHuman-readable description of the rule's attribute filters, if any (e.g., path contains /pricing). Omitted when the rule has no filters.
snapshotarrayCurrent rule weights from active rulesets (highest absolute value first)
snapshot[].event_typestringEvent type name
snapshot[].weightintegerPoint value assigned to this event type by active rules
decay_appliedintegerTotal decay points applied in the window (negative value, aggregated across rulesets)
inorganic_countintegerNumber of events excluded by inorganic activity filters
range_hoursintegerThe time window used for the explanation
score_reset_attimestampWhen the lead's scores were last reset (null if never reset)
reset_excluded_countintegerNumber of pre-reset events excluded from scoring. These events still exist in history but no longer contribute to the score.

Examples​

Default 24-hour window:

curl -X GET "https://api.kenbun.io/lead/ld_abc123/score-explain" \
  -H "Authorization: Bearer <token>"

Custom 72-hour window:

curl -X GET "https://api.kenbun.io/lead/ld_abc123/score-explain?hours=72" \
  -H "Authorization: Bearer <token>"

Common Errors​

StatusMeaningSolution
401UnauthorizedCheck authentication credentials
404Not FoundLead does not exist or is not accessible

Score Reset Awareness​

When a lead's scores have been reset, the explanation reflects this:

  • score_reset_at shows the timestamp of the most recent reset
  • reset_excluded_count indicates how many historical events no longer contribute to the score
  • Only events that occurred after the reset contribute to the current score breakdown

In the kenbun UI, the Score Explain panel displays a banner when a reset has occurred, showing the reset date and the number of excluded events.

Notes​

  • This endpoint is OU-scoped to the active Organizational Unit
  • Only active rules in active rulesets are considered
  • Both global and OU-specific rules are included in the explanation
  • top_drivers returns one row per scoring rule, not one row per event type. If two rules match the same event type but with different attribute filters (for example, one rule scoring all page views and a separate rule scoring page views where path contains /pricing), they appear as separate rows. Each row includes a filter_label describing its conditions.
  • When a lead triggers multiple rules for the same event, each event is attributed to the first matching rule (by rule priority). This mirrors how kenbun's scoring engine assigns points.
  • Use in combination with Score History for a complete picture of score trends

Sharing a Score Explanation​

You can share a read-only view of any lead's score explanation with people who don't have a kenbun account. Use the share feature to brief stakeholders, hand off leads across teams, or document scoring for a deal review.

From the kenbun UI: Open the Score Explain panel on any lead detail page and click Share. kenbun generates a link that expires after 7 days.

Via the API: Use POST /leads/{id}/share-explain to create a share link programmatically. The response includes a share_url that recipients can open in a browser — no login required.

See Share Score Explanation for full API documentation.