# Notification Preferences

{% hint style="warning" %}
**Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)).
{% endhint %}

## Notification Preferences API

API for managing notification preferences

**A NotificationPreference object looks like:**

```js
{
  "href": "https://canvas.instructure.com/users/1/communication_channels/email/student@example.edu/notification_preferences/new_announcement",
  // The notification this preference belongs to
  "notification": "new_announcement",
  // The category of that notification
  "category": "announcement",
  // How often to send notifications to this communication channel for the given
  // notification. Possible values are 'immediately', 'daily', 'weekly', and
  // 'never'
  "frequency": "daily"
}
```

### [List preferences](#method.notification_preferences.index) <a href="#method.notification_preferences.index" id="method.notification_preferences.index"></a>

[NotificationPreferencesController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`GET /api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preferences`**

**Scope:** `url:GET|/api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preferences`

**`GET /api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences`**

**Scope:** `url:GET|/api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences`

Fetch all preferences for the given communication channel

Returns a list of [NotificationPreference](#notificationpreference) objects.

### [List of preference categories](#method.notification_preferences.category_index) <a href="#method.notification_preferences.category_index" id="method.notification_preferences.category_index"></a>

[NotificationPreferencesController#category\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`GET /api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preference_categories`**

**Scope:** `url:GET|/api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preference_categories`

Fetch all notification preference categories for the given communication channel

### [Get a preference](#method.notification_preferences.show) <a href="#method.notification_preferences.show" id="method.notification_preferences.show"></a>

[NotificationPreferencesController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`GET /api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preferences/:notification`**

**Scope:** `url:GET|/api/v1/users/:user_id/communication_channels/:communication_channel_id/notification_preferences/:notification`

**`GET /api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences/:notification`**

**Scope:** `url:GET|/api/v1/users/:user_id/communication_channels/:type/:address/notification_preferences/:notification`

Fetch the preference for the given notification for the given communication channel

Returns a [NotificationPreference](#notificationpreference) object.

### [Update a preference](#method.notification_preferences.update) <a href="#method.notification_preferences.update" id="method.notification_preferences.update"></a>

[NotificationPreferencesController#update](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`PUT /api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences/:notification`**

**Scope:** `url:PUT|/api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences/:notification`

**`PUT /api/v1/users/self/communication_channels/:type/:address/notification_preferences/:notification`**

**Scope:** `url:PUT|/api/v1/users/self/communication_channels/:type/:address/notification_preferences/:notification`

Change the preference for a single notification for a single communication channel

**Request Parameters:**

| Parameter                             | Type              | Description                                 |
| ------------------------------------- | ----------------- | ------------------------------------------- |
| `notification_preferences[frequency]` | Required `string` | The desired frequency for this notification |

### [Update preferences by category](#method.notification_preferences.update_preferences_by_category) <a href="#method.notification_preferences.update_preferences_by_category" id="method.notification_preferences.update_preferences_by_category"></a>

[NotificationPreferencesController#update\_preferences\_by\_category](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`PUT /api/v1/users/self/communication_channels/:communication_channel_id/notification_preference_categories/:category`**

**Scope:** `url:PUT|/api/v1/users/self/communication_channels/:communication_channel_id/notification_preference_categories/:category`

Change the preferences for multiple notifications based on the category for a single communication channel

**Request Parameters:**

| Parameter                             | Type              | Description                                                                                                      |
| ------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------- |
| `category`                            | `string`          | The name of the category. Must be parameterized (e.g. The category “Course Content” should be “course\_content”) |
| `notification_preferences[frequency]` | Required `string` | The desired frequency for each notification in the category                                                      |

### [Update multiple preferences](#method.notification_preferences.update_all) <a href="#method.notification_preferences.update_all" id="method.notification_preferences.update_all"></a>

[NotificationPreferencesController#update\_all](https://github.com/instructure/canvas-lms/blob/master/app/controllers/notification_preferences_controller.rb)

**`PUT /api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences`**

**Scope:** `url:PUT|/api/v1/users/self/communication_channels/:communication_channel_id/notification_preferences`

**`PUT /api/v1/users/self/communication_channels/:type/:address/notification_preferences`**

**Scope:** `url:PUT|/api/v1/users/self/communication_channels/:type/:address/notification_preferences`

Change the preferences for multiple notifications for a single communication channel at once

**Request Parameters:**

| Parameter                                  | Type              | Description                                 |
| ------------------------------------------ | ----------------- | ------------------------------------------- |
| `notification_preferences[<X>][frequency]` | Required `string` | The desired frequency for \<X> notification |

***

This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developerdocs.instructure.com/services/canvas/resources/notification_preferences.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.