Engagement Level by ID API
Update or delete an individual engagement level.
PUT /engagement-scoring/levels/{id}
Update an existing engagement level. Only the fields you provide are updated; omitted fields remain unchanged.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Level identifier (path parameter) |
Request Body
All fields are optional. Only provided fields will be updated.
| Field | Type | Description |
|---|---|---|
name | string | Level label (e.g., "Hot", "Warm", "Cold") |
min_score | integer | Minimum score (inclusive) |
max_score | integer or null | Maximum score (inclusive). Use null for no upper limit |
color | string | Hex color code for display |
order | integer | Display order |
{
"name": "Freezing Cold",
"min_score": 0,
"max_score": 19,
"color": "#64748b"
}
Response
200 OK
{
"id": "level-123",
"name": "Freezing Cold",
"min_score": 0,
"max_score": 19,
"color": "#64748b",
"order": 1,
"updated_at": "2025-01-15T12:00:00Z"
}
Example
curl -X PUT "https://api.kenbun.io/engagement-scoring/levels/level-123" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"name": "Freezing Cold", "min_score": 0, "max_score": 19, "color": "#64748b"}'
Common Errors
| Status | Meaning | Solution |
|---|---|---|
| 400 | Bad Request | Score range overlaps with another level |
| 401 | Unauthorized | Check authentication credentials |
DELETE /engagement-scoring/levels/{id}
Delete an engagement level. Leads that matched this level will show as "Unclassified" until another level covers their score range.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Level identifier (path parameter) |
Response
204 No Content
Example
curl -X DELETE "https://api.kenbun.io/engagement-scoring/levels/level-123" \
-H "Authorization: Bearer <token>"
Common Errors
| Status | Meaning | Solution |
|---|---|---|
| 400 | Bad Request | Cannot delete the last remaining level |
| 401 | Unauthorized | Check authentication credentials |
Notes
- Historical level assignments are preserved even after a level is deleted
- Ensure other levels cover the full score range to avoid gaps where leads appear as "Unclassified"
Related Endpoints
- Engagement Levels - List and create engagement levels
- Profile Levels - Manage profile-based levels