Decay Rules API

Manage score decay rules that automatically reduce lead scores over time based on inactivity. Decay rules prevent stale leads from maintaining artificially high scores.

GET /decays

List all decay rules for the active Organizational Unit.

Request

No query parameters required.

Response

200 OK

{
  "decays": [
    {
      "id": "decay-123",
      "name": "7-Day Inactivity Decay",
      "points": -5,
      "interval_days": 7,
      "active": true,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique decay rule identifier
name	string	Decay rule name
points	integer	Points to subtract each interval (negative value)
interval_days	integer	Number of days of inactivity before decay applies
active	boolean	Whether the rule is currently active
created_at	timestamp	When the rule was created

Example

curl -X GET "https://api.kenbun.io/decays" \
  -H "Authorization: Bearer <token>"

Common Errors

Status	Meaning	Solution
401	Unauthorized	Check authentication token

---

POST /decays

Create a new decay rule.

Request

Parameter	Type	Required	Description
name	string	Yes	Rule name
points	integer	Yes	Points to subtract per interval (negative value)
interval_days	integer	Yes	Days of inactivity before decay starts

Request Body

{
  "name": "Weekly Decay",
  "points": -5,
  "interval_days": 7
}

Response

201 Created

Returns the created decay rule.

Example

curl -X POST "https://api.kenbun.io/decays" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekly Decay",
    "points": -5,
    "interval_days": 7
  }'

Common Errors

Status	Meaning	Solution
400	Bad Request	Missing required fields
401	Unauthorized	Check authentication token

---

Notes

• Decay rules are OU-scoped to the active Organizational Unit
• Decay is applied automatically on a configured schedule
• A lead's score will not drop below zero (unless negative scores are enabled in scoring settings)
• Use decay rules to ensure your highest-priority leads are truly active, not just historically engaged

Related Endpoints

• Decay Rule by ID - Update or delete a decay rule
• Scoring Settings - Configure negative score behavior