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

Parameter	Type	Required	Description
leadID	string	Yes	Lead identifier (path parameter)
hours	integer	No	Time window in hours (default: 24)

Response

200 OK

{
  "top_drivers": [
    { "event_type": "webinar_attend", "total": 30 },
    { "event_type": "email_click", "total": 5 }
  ],
  "snapshot": [
    { "event_type": "webinar_attend", "weight": 30 },
    { "event_type": "email_click", "weight": 5 }
  ],
  "decay_applied": -6,
  "range_hours": 24
}

Response Fields

Field	Type	Description
top_drivers	array	Event types that contributed the most to the lead's score in the window
top_drivers[].event_type	string	Event type name
top_drivers[].total	integer	Total points contributed by this event type
snapshot	array	Current rule weights from active rulesets (highest absolute value first)
snapshot[].event_type	string	Event type name
snapshot[].weight	integer	Point value assigned to this event type by active rules
decay_applied	integer	Total decay points applied in the window (negative value, aggregated across rulesets)
range_hours	integer	The time window used for the explanation

Examples

Default 24-hour window:

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

Custom 72-hour window:

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

Common Errors

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

---

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
• Use in combination with Score History for a complete picture of score trends

Related Endpoints

• Score - Get current score breakdown
• Score History - View score changes over time
• Score Gains - See recent scoring activity across leads