---
title: "Default Notifications"
description: "The organization's default notification chain: what new users start with when their personal notification settings are first created."
---

`GET /api/im/notification-template` · `PUT /api/im/notification-template`

The default notifications are the chain a person starts with. They are copied into a person's [personal notification settings](/api/incident-management/notification-settings) when those are created, which happens the first time the person (or an admin through [User notification settings](/api/incident-management/user-notification-settings)) opens them. **They are not retroactive**: people who already have settings keep theirs, and everyone can change their own chain afterwards.

`sms` and `voice` steps wait until the person has confirmed a phone number.

## 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.

## Get the default notifications

`GET /api/im/notification-template`

### Example (cURL)

```bash
curl -X GET "$BASE_URL/api/im/notification-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"
```

### Response

```json
{
  "channels": { "push": true, "sms": true, "voice": false, "email": true },
  "rules": [
    { "urgency": "high", "delayMinutes": 0, "channel": "push" },
    { "urgency": "high", "delayMinutes": 5, "channel": "sms" },
    { "urgency": "low", "delayMinutes": 0, "channel": "email" }
  ],
  "updatedAt": "2026-10-28T09:12:00.000Z"
}
```

Before the first save the answer is `{ "channels": {}, "rules": [], "updatedAt": null }`, and new users start without a chain.

## Set the default notifications

`PUT /api/im/notification-template`

Replaces the whole template.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `rules` | array | Yes | The 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 (without `channels`) switches the template off. |
| `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. |

Unknown fields are rejected.

### Example (cURL)

```bash
curl -X PUT "$BASE_URL/api/im/notification-template" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"rules":[{"urgency":"high","delayMinutes":0,"channel":"push"},{"urgency":"high","delayMinutes":5,"channel":"sms"},{"urgency":"low","delayMinutes":0,"channel":"email"}]}'
```

### Response

`200 OK`: the template after the write, same shape as the GET response. Every change is recorded in the audit log.

## 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 twice
- `401 Unauthorized` when not authenticated
- `403 Forbidden` (`forbidden`) when the caller is not an `admin` of the organization
- `403 Forbidden` (`imAccessDenied`) for a customer login or a customer-bound token
- `403 Forbidden` (`imNotEnabled`) when Incident Management is not enabled for the organization