Skip to main content

Notification Preferences API

Manage your personal notification preferences programmatically. These endpoints control whether kenbun sends you direct messages when triggers fire on leads you own, and which event types you want muted.

Preferences are personal — you can only read or write your own settings, never another team member's. Each setting is scoped to the active Organizational Unit.

GET /me/notification-prefs​

Retrieve your notification preferences for the active Organizational Unit. The response always lists all four canonical event types. Any event type you have not explicitly muted defaults to muted: false.

Authentication​

Required: Yes. Bearer token (JWT) for browser/SPA clients.

Request​

Endpoint: GET /me/notification-prefs

Headers:

Accept: application/json

Example:

curl -X GET "https://api.kenbun.io/me/notification-prefs" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"

Response​

Status: 200 OK

Response Fields:

FieldTypeDescription
notifications_enabledbooleanMaster toggle. When false, all kenbun direct messages to this user are muted regardless of per-event-type settings.
slack_user_idstring or nullA masked version of the user's Slack identifier (for example, U12•••XYZ). null if the user has not been mapped yet.
prefsarrayOne entry per canonical event type.
prefs[].event_typestringOne of milestone.entered, milestone.exited, sequence.completed, surge.fired.
prefs[].mutedbooleantrue if this event type is muted for the user.

Example Response:

{
  "notifications_enabled": true,
  "slack_user_id": "U12•••XYZ",
  "prefs": [
    { "event_type": "milestone.entered",  "muted": false },
    { "event_type": "milestone.exited",   "muted": true  },
    { "event_type": "sequence.completed", "muted": false },
    { "event_type": "surge.fired",        "muted": false }
  ]
}

Common Errors​

StatusMeaningSolution
400No active Organizational UnitSet an active Organizational Unit before calling.
401UnauthorizedVerify your bearer token is valid.
500Internal Server ErrorRetry later or contact support.

PUT /me/notification-prefs​

Update your master toggle, your per-event-type mute settings, or both. Both fields are optional. Omitted fields are left unchanged.

Authentication​

Required: Yes. Bearer token (JWT).

Request​

Endpoint: PUT /me/notification-prefs

Headers:

Content-Type: application/json
Accept: application/json

Request Body​

FieldRequiredTypeDescription
notifications_enabledNobooleanMaster toggle. When false, all direct messages are muted. When omitted, the existing value is preserved.
prefsNoarrayOne entry per event type to update. Event types not included in the array are left at their current setting.
prefs[].event_typeYes (within an entry)stringOne of the four canonical event types. Any other value returns 400.
prefs[].mutedYes (within an entry)booleantrue to mute this event type, false to enable.

Example Request Body:

{
  "notifications_enabled": true,
  "prefs": [
    { "event_type": "milestone.exited", "muted": true },
    { "event_type": "surge.fired",      "muted": false }
  ]
}

Example:

curl -X PUT "https://api.kenbun.io/me/notification-prefs" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "notifications_enabled": true,
    "prefs": [
      { "event_type": "milestone.exited", "muted": true }
    ]
  }'

Response​

Status: 200 OK

{ "status": "ok" }

Common Errors​

StatusMeaningSolution
400Unknown event_type valueUse one of milestone.entered, milestone.exited, sequence.completed, surge.fired.
400No active Organizational UnitSet an active Organizational Unit before calling.
400Malformed JSON bodyVerify the request body is valid JSON.
401UnauthorizedVerify your bearer token.
500Internal Server ErrorRetry later.

Canonical Event Types​

The four event types accepted by these endpoints map to the trigger types in kenbun:

Event TypeFires For
milestone.enteredA lead's score crosses a milestone threshold upward
milestone.exitedA lead's score drops below a milestone threshold
sequence.completedA lead completes a configured event sequence
surge.firedA surge trigger fires on a lead

Any other value in prefs[].event_type causes the request to be rejected with a 400 response.

Notes​

  • Preferences are stored per user, per Organizational Unit. The Organizational Unit is read automatically from your account context.
  • Default behavior is opt-out: new users have no stored preferences and receive every event type until they explicitly mute one.
  • The slack_user_id field is masked for display purposes only. It is never returned in cleartext from this endpoint.