> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/canvas/resources/account_notifications.md).

# Account Notifications

API for account notifications.

#### An AccountNotification object looks like: <a href="#accountnotification" id="accountnotification"></a>

```js
{
  // The subject of the notifications
  "subject": "Attention Students",
  // The message to be sent in the notification.
  "message": "This is a test of the notification system.",
  // When to send out the notification.
  "start_at": "2013-08-28T23:59:00-06:00",
  // When to expire the notification.
  "end_at": "2013-08-29T23:59:00-06:00",
  // The icon to display with the message.  Defaults to warning.
  "icon": "information",
  // (Deprecated) The roles to send the notification to.  If roles is not passed
  // it defaults to all roles
  "roles": ["StudentEnrollment"],
  // The roles to send the notification to.  If roles is not passed it defaults to
  // all roles
  "role_ids": [1],
  // The author of the notification. Available only to admins using include_all.
  "author": {"id":1,"name":"John Doe"}
}
```

## [Index of active global notification for the user](#method.account_notifications.user_index) <a href="#method.account_notifications.user_index" id="method.account_notifications.user_index"></a>

[AccountNotificationsController#user\_index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb)

#### `GET /api/v1/accounts/:account_id/account_notifications`

**Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications`

Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include\_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include\_all parameter.

#### Request Parameters:

| Parameter        | Type      | Description                                                                                                         |
| ---------------- | --------- | ------------------------------------------------------------------------------------------------------------------- |
| `include_past`   | `boolean` | Include past and dismissed global announcements.                                                                    |
| `include_all`    | `boolean` | Include all global announcements, regardless of user's role or availability date. Only available to account admins. |
| `show_is_closed` | `boolean` | Include a flag for each notification indicating whether it has been read by the user.                               |

#### Example Request:

```bash
curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/users/self/account_notifications
```

Returns a list of [AccountNotification](#accountnotification) objects.

## [Show a global notification](#method.account_notifications.show) <a href="#method.account_notifications.show" id="method.account_notifications.show"></a>

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

#### `GET /api/v1/accounts/:account_id/account_notifications/:id`

**Scope:** `url:GET|/api/v1/accounts/:account_id/account_notifications/:id`

Returns a global notification for the current user A notification that has been closed by the user will not be returned

#### Example Request:

```bash
curl -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/users/self/account_notifications/4
```

Returns an [AccountNotification](#accountnotification) object.

## [Create a global notification](#method.account_notifications.create) <a href="#method.account_notifications.create" id="method.account_notifications.create"></a>

[AccountNotificationsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb)

#### `POST /api/v1/accounts/:account_id/account_notifications`

**Scope:** `url:POST|/api/v1/accounts/:account_id/account_notifications`

Create and return a new global notification for an account.

#### Request Parameters:

| Parameter                        | Type                | Description                                                                                                                                                                                                      |
| -------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_notification[subject]`  | Required `string`   | The subject of the notification.                                                                                                                                                                                 |
| `account_notification[message]`  | Required `string`   | The message body of the notification.                                                                                                                                                                            |
| `account_notification[start_at]` | Required `DateTime` | <p>The start date and time of the notification in ISO8601 format.<br>e.g. 2014-01-01T01:00Z</p>                                                                                                                  |
| `account_notification[end_at]`   | Required `DateTime` | <p>The end date and time of the notification in ISO8601 format.<br>e.g. 2014-01-01T01:00Z</p>                                                                                                                    |
| `account_notification[icon]`     | `string`            | <p>The icon to display with the notification.<br>Note: Defaults to warning. Allowed values: <code>warning</code>, <code>information</code>, <code>question</code>, <code>error</code>, <code>calendar</code></p> |
| `account_notification_roles[]`   | `string`            | <p>The role(s) to send global notification to. Note: ommitting this field will send to everyone<br>Example:<br>account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"]</p>                     |

#### Example Request:

```bash
curl -X POST -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/account_notifications \
-d 'account_notification[subject]=New notification' \
-d 'account_notification[start_at]=2014-01-01T00:00:00Z' \
-d 'account_notification[end_at]=2014-02-01T00:00:00Z' \
-d 'account_notification[message]=This is a global notification'
```

#### Example Response:

```js
{
  "subject": "New notification",
  "start_at": "2014-01-01T00:00:00Z",
  "end_at": "2014-02-01T00:00:00Z",
  "message": "This is a global notification"
}
```

## [Update a global notification](#method.account_notifications.update) <a href="#method.account_notifications.update" id="method.account_notifications.update"></a>

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

#### `PUT /api/v1/accounts/:account_id/account_notifications/:id`

**Scope:** `url:PUT|/api/v1/accounts/:account_id/account_notifications/:id`

Update global notification for an account.

#### Request Parameters:

| Parameter                        | Type       | Description                                                                                                                                                                                  |
| -------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_notification[subject]`  | `string`   | The subject of the notification.                                                                                                                                                             |
| `account_notification[message]`  | `string`   | The message body of the notification.                                                                                                                                                        |
| `account_notification[start_at]` | `DateTime` | <p>The start date and time of the notification in ISO8601 format.<br>e.g. 2014-01-01T01:00Z</p>                                                                                              |
| `account_notification[end_at]`   | `DateTime` | <p>The end date and time of the notification in ISO8601 format.<br>e.g. 2014-01-01T01:00Z</p>                                                                                                |
| `account_notification[icon]`     | `string`   | The icon to display with the notification. Allowed values: `warning`, `information`, `question`, `error`, `calendar`                                                                         |
| `account_notification_roles[]`   | `string`   | <p>The role(s) to send global notification to. Note: ommitting this field will send to everyone<br>Example:<br>account\_notification\_roles: \["StudentEnrollment", "TeacherEnrollment"]</p> |

#### Example Request:

```bash
curl -X PUT -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/account_notifications/1 \
-d 'account_notification[subject]=New notification' \
-d 'account_notification[start_at]=2014-01-01T00:00:00Z' \
-d 'account_notification[end_at]=2014-02-01T00:00:00Z' \
-d 'account_notification[message]=This is a global notification'
```

#### Example Response:

```js
{
  "subject": "New notification",
  "start_at": "2014-01-01T00:00:00Z",
  "end_at": "2014-02-01T00:00:00Z",
  "message": "This is a global notification"
}
```

## [Close notification for user. Destroy notification for admin](#method.account_notifications.user_close_notification) <a href="#method.account_notifications.user_close_notification" id="method.account_notifications.user_close_notification"></a>

[AccountNotificationsController#user\_close\_notification](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_notifications_controller.rb)

#### `DELETE /api/v1/accounts/:account_id/account_notifications/:id`

**Scope:** `url:DELETE|/api/v1/accounts/:account_id/account_notifications/:id`

If the current user no longer wants to see this account notification, it can be closed with this call. This affects the current user only.

If the current user is an admin and they pass a remove parameter with a value of "true", the account notification will be destroyed. This affects all users.

#### Request Parameters:

| Parameter | Type      | Description                       |
| --------- | --------- | --------------------------------- |
| `remove`  | `boolean` | Destroy the account notification. |

#### Example Request:

```bash
curl -X DELETE -H 'Authorization: Bearer <token>' \
https://<canvas>/api/v1/accounts/2/account_notifications/4
```

Returns an [AccountNotification](#accountnotification) object.

***

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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