Skip to main content

Reset Lead Scores API

Reset all engagement scores for a lead to zero. This is useful when a lead's score no longer reflects their current intent -- for example, after a long period of inactivity, a change in role, or when you want to give a lead a fresh start without losing their event history.

When to Use This​

  • Stale scores: A lead accumulated points months ago but hasn't engaged recently. Rather than waiting for decay rules to gradually reduce the score, reset it immediately.
  • Re-engagement campaigns: You're launching a new campaign and want to measure fresh engagement from a clean baseline.
  • Data correction: Events were ingested incorrectly and inflated a lead's score. After fixing the data, reset the score so only new, accurate events contribute.
  • Role or ownership changes: A lead changed roles or was reassigned, and their previous engagement history is no longer relevant for prioritization.

POST /leads/{leadID}/reset-scores​

Zeros all engagement scores for the specified lead. Events and score history are preserved for audit purposes, but pre-reset event contributions are removed so that backfill operations do not undo the reset.

What Happens During a Reset​

  1. All engagement scores for the lead are set to zero across every ruleset
  2. Pre-reset event score contributions are cleared (so rescoring or backfills start fresh)
  3. A score_reset event is logged in the lead's timeline with the previous scores
  4. The lead's engagement level is recalculated to reflect the new zero score
  5. A real-time update is sent so the UI reflects the change immediately

Request​

ParameterTypeRequiredDescription
leadIDstringYesLead identifier (path parameter)

No request body is required.

Response​

200 OK

{
  "status": "ok",
  "lead_id": "ld_abc123",
  "previous_scores": {
    "ruleset-engagement": 85,
    "ruleset-campaign-q1": 40
  }
}

Response Fields​

FieldTypeDescription
statusstringAlways ok on success
lead_idstringThe lead whose scores were reset
previous_scoresobjectMap of ruleset ID to the score that was zeroed. Useful for logging or undo workflows.

Example​

curl -X POST "https://your-instance.com/leads/ld_abc123/reset-scores" \
  -u "CLIENT_ID:CLIENT_SECRET"

Common Errors​

StatusMeaningSolution
400Bad RequestleadID is missing or malformed
401UnauthorizedCheck your API credentials
404Not FoundLead does not exist or is not accessible in your active OU
500Internal Server ErrorRetry the request. If the issue persists, contact support.

How Score Reset Affects Other Features​

Score Explain​

After a reset, the Score Explain endpoint includes two additional fields:

  • score_reset_at -- timestamp of the most recent reset
  • reset_excluded_count -- number of pre-reset events that are no longer contributing to the score

The Score Explain panel in the UI displays a banner indicating when the reset occurred and how many events were excluded.

Score History​

The reset is recorded as a score_reset event in the lead's timeline. Score History will show the score dropping to zero at the reset timestamp, providing a clear audit trail.

Decay Rules​

Decay rules continue to operate normally after a reset. Since the score is already zero, decay has no further effect until new events add points.

Engagement Levels​

The lead's engagement level is immediately recalculated after the reset. If your lowest engagement level threshold is zero, the lead will move to that level.

Triggers​

Milestone and sequence triggers evaluate based on the current score. A reset may cause a lead to fall below trigger thresholds. Future events that raise the score above a threshold will fire triggers as expected.

Best Practices​

  1. Use reset sparingly. Decay rules handle gradual score reduction automatically. Reserve resets for cases where the score is fundamentally misleading.
  2. Document the reason. The reset is logged with your user identity in the audit trail, but consider noting the reason in your team's workflow tools.
  3. Check previous scores. The response includes previous_scores so you can verify what was reset and keep a record if needed.
  4. Combine with re-engagement. After resetting a lead, send targeted content to start building a fresh engagement signal.

Notes​

  • This endpoint is OU-scoped to the active Organizational Unit
  • If the lead's scores are already all zero, the endpoint returns successfully without making changes
  • Profile scores (fit-based scoring) are not affected by this endpoint -- only engagement scores are reset
  • The operation is audited and includes the identity of the user who performed the reset