User Notification Settings
Organization admins read and set one person's notification settings: phone number, delivery channels and the whole notification chain.
GET /api/im/users/:userId/notification-settings · PUT /api/im/users/:userId/notification-settings
An organization admin sets up how a person is paged, for example while onboarding a new on-call responder, so the person does not have to do it themselves. These are the same settings the person sees and edits under Personal notification settings. The last write wins: the person can change everything afterwards, and an admin can set it again at any time. The person sees a notice "Changed by (admin) on (date)" on their notification page.
sms and voice steps are stored even while the phone number is not verified. They wait: every page until then is logged as skipped (reason unverified), and the person is asked to confirm the number when they next sign in. Nothing is sent to a number nobody has confirmed.
Authentication
Requires the admin role of the organization, with a user session or an organization-wide API token (the token runs with the role of the user who created it). Customer-bound tokens and customer logins are refused. Incident Management must be enabled for the organization.
The target user must belong to your organization, be active, and have an IM-eligible role (admin, editor or responder).
Get a user's settings
GET /api/im/users/:userId/notification-settings
Creates the settings on first access, starting from the default notifications, exactly as when the person opens them.
Example (cURL)
curl -X GET "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \
-H "Authorization: Bearer $TOKEN" \
-H "Accept: application/json"Response
{
"userId": "usr_8f2c",
"id": 31,
"phoneNumber": "+491701234567",
"phoneVerified": false,
"channels": { "push": true, "sms": true, "voice": false, "email": true },
"severityChannels": {},
"rules": [
{ "id": 201, "urgency": "high", "delayMinutes": 0, "channel": "push" },
{ "id": 202, "urgency": "high", "delayMinutes": 5, "channel": "sms" },
{ "id": 203, "urgency": "low", "delayMinutes": 0, "channel": "email" }
],
"lastAdminChangeAt": "2026-10-28T09:12:00.000Z",
"lastAdminChangeBy": { "id": "usr_admin", "name": "Ada Admin" }
}phoneVerified: false with sms/voice rules means those steps wait for the person to confirm the number. The severity filter (severityChannels) is shown but not set here; it stays the person's own choice.
Set a user's settings
PUT /api/im/users/:userId/notification-settings
Replaces the person's whole notification chain with rules. Rules not in the list are deleted. A request that changes nothing writes nothing and does not update lastAdminChangeAt.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
rules | array | Yes | The whole chain, at most 64 steps. Each step { "urgency": "high" or "low", "delayMinutes": 0..1440, "channel": "push", "sms", "voice" or "email" }. Each urgency/delay/channel combination at most once. An empty list removes every rule. |
channels | object | No | The four delivery switches (push, sms, voice, email → boolean). Omitted: a channel is on exactly when rules has a step for it. Other switches the person set (shift reminders) are kept. |
phoneNumber | string or null | No | E.164 number, e.g. +491701234567. Omitted: unchanged. null removes it. A different number is unverified until the person confirms it, and any pending verification code is discarded. |
Unknown fields are rejected.
Example (cURL)
curl -X PUT "$BASE_URL/api/im/users/usr_8f2c/notification-settings" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"phoneNumber":"+491701234567","rules":[{"urgency":"high","delayMinutes":0,"channel":"push"},{"urgency":"high","delayMinutes":5,"channel":"sms"},{"urgency":"low","delayMinutes":0,"channel":"email"}]}'Response
200 OK: the settings after the write, same shape as the GET response.
Every change is recorded in the audit log with the admin, the person and each field from old to new value; phone numbers appear there masked.
Common errors
400 Bad Request(invalidRequestBody) for an invalid body: unknown field, channel or urgency, delay outside 0 to 1440, more than 64 steps, the same urgency/delay/channel twice400 Bad Request(invalidPhoneNumber) whenphoneNumberis not in E.164 format400 Bad Request(imUserNotEligible) when the user is inactive or has no IM-eligible role401 Unauthorizedwhen not authenticated403 Forbidden(forbidden) when the caller is not anadminof the organization403 Forbidden(imAccessDenied) for a customer login or a customer-bound token403 Forbidden(imNotEnabled) when Incident Management is not enabled for the organization404 Not Found(userNotFound) when the user does not exist or belongs to another organization
Personal Notification Settings
How Incident Management reaches you: channels, notification rules per urgency, channels per severity, phone verification, test notifications and your notification log.
Default Notifications
The organization's default notification chain: what new users start with when their personal notification settings are first created.