Score History API

Retrieve historical score data for leads to analyze engagement trends over time.

GET /lead/{leadID}/score-history

Get score history snapshots for a specific lead.

Request

Parameter	Type	Required	Description
leadID	string	Yes	Lead identifier (path parameter)
days	integer	No	Number of days to retrieve (default: 30, max: 90)
ruleset_id	string	No	Filter to specific ruleset
start_date	string	No	Start date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
end_date	string	No	End date in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)

Query Parameters

Use either days for relative time ranges or start_date/end_date for absolute ranges.

Examples:

• ?days=7 - Last 7 days
• ?days=30 - Last 30 days (default)
• ?days=90 - Last 90 days (maximum retention)
• ?start_date=2025-01-01T00:00:00Z&end_date=2025-01-15T23:59:59Z - Specific range
• ?ruleset_id=ruleset_abc123 - Filter to specific scoring ruleset

Response

200 OK

{
  "lead_id": "ld_123",
  "snapshots": [
    {
      "snapshot_at": "2025-01-15T10:00:00Z",
      "score": 45,
      "ruleset_id": "ruleset_default"
    },
    {
      "snapshot_at": "2025-01-15T11:00:00Z",
      "score": 50,
      "ruleset_id": "ruleset_default"
    },
    {
      "snapshot_at": "2025-01-15T12:00:00Z",
      "score": 50,
      "ruleset_id": "ruleset_default"
    },
    {
      "snapshot_at": "2025-01-15T13:00:00Z",
      "score": 55,
      "ruleset_id": "ruleset_default"
    }
  ],
  "count": 4,
  "period": {
    "start": "2025-01-15T00:00:00Z",
    "end": "2025-01-16T00:00:00Z"
  }
}

Response Fields

Field	Type	Description
lead_id	string	Lead identifier
snapshots	array	Array of score snapshot objects
snapshots[].snapshot_at	timestamp	When the snapshot was taken
snapshots[].score	integer	Lead's score at that time
snapshots[].ruleset_id	string	Ruleset identifier (optional)
count	integer	Number of snapshots returned
period	object	Time period covered
period.start	timestamp	Start of the period
period.end	timestamp	End of the period

Examples

Get Last 30 Days (default):

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

Get Last 7 Days:

curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?days=7" \
  -H "Authorization: Bearer <token>"

Get Specific Date Range:

curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?start_date=2025-01-01T00:00:00Z&end_date=2025-01-15T23:59:59Z" \
  -H "Authorization: Bearer <token>"

Filter by Ruleset:

curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?ruleset_id=ruleset_abc123" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
400	Bad Request	Check date format or days parameter
401	Unauthorized	Check authentication token
404	Not Found	Lead does not exist or not accessible

---

Understanding Score Snapshots

Snapshot Frequency

• Snapshots are taken hourly for all leads
• Background worker runs every hour
• Captures current score at time of snapshot
• No action required from users

Retention Period

• Default retention: 90 days
• Configurable per organization
• Older snapshots automatically deleted
• Historical data before snapshot feature launch not available

Data Accuracy

• Snapshots reflect score at capture time
• May not include events ingested between snapshots
• For real-time scores, use GET /score/{leadID}
• Snapshots useful for trends, not exact point-in-time accuracy

---

Use Cases

Identify Engagement Trends

Analyze whether a lead is becoming more or less engaged over time.

# Get 30-day history
curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?days=30" \
  -H "Authorization: Bearer <token>"

# Calculate trend
# - If most recent score > oldest score: Upward trend
# - If most recent score < oldest score: Downward trend
# - Plot scores to visualize pattern

Measure Campaign Impact

Compare scores before and after a marketing campaign.

# Get data for campaign period
curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?start_date=2025-01-01T00:00:00Z&end_date=2025-01-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"

# Compare average score before vs after campaign launch
# Identify spike in engagement

Build Score Trend Visualizations

Create charts showing score evolution for dashboards.

# Fetch score history
curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?days=90" \
  -H "Authorization: Bearer <token>"

# Use snapshots array to plot line chart
# X-axis: snapshot_at timestamps
# Y-axis: score values

Compare Multiple Rulesets

If using multiple scoring rulesets, compare trends across rulesets.

# Get engagement score history
curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?ruleset_id=ruleset_engagement" \
  -H "Authorization: Bearer <token>"

# Get profile score history
curl -X GET "https://api.leadvibe.com/lead/ld_123/score-history?ruleset_id=ruleset_profile" \
  -H "Authorization: Bearer <token>"

# Compare which score type is changing

---

Interpreting Score Patterns

Common Patterns

Steady Growth:

• Score increases consistently over time
• Indicates ongoing engagement
• Good candidate for sales outreach

Sharp Spike:

• Sudden jump in score
• May indicate campaign response or buying intent
• Check lead's activity timeline for context

Plateau:

• Score remains stable
• Lead engaged but not taking new actions
• Consider new nurture content

Decline:

• Score decreasing over time
• May indicate lost interest or decay rules
• Re-engagement campaign may help

Inactive (Flat Line):

• No score changes
• Lead hasn't engaged recently
• May need reactivation

Taking Action Based on Trends

Upward Trends:

• Prioritize for sales outreach
• Lead is actively researching
• Strike while interest is high

Downward Trends:

• Add to re-engagement campaign
• Review content strategy
• Check if competitor may be winning

Spikes:

• Immediate follow-up recommended
• Lead showing buying signals
• Coordinate with sales quickly

Plateaus:

• Introduce new content
• Try different engagement channel
• May need more nurturing time

---

Notes

• Score history is OU-scoped like all lead data
• Snapshots start when feature was enabled (no retroactive data)
• For leads with no activity, snapshots will show flat line at current score
• Background worker may be delayed during high load (snapshots catch up)
• Snapshot frequency and retention are configurable per organization
• Use in combination with GET /lead/\{leadID\}/score-explain for full picture