Get all destination entries

GET /v1/distribution_lists/{account_id}/destinations

Retrieve all destinations in the distribution list for the specified account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• notificationapi.accountemails.view

Request

Response

200 - Successfully retrieved all destinations from the distribution list.

destinations

array

Array of destination entries.

400 -

403 -

404 -

429 -

500 -

Add a destination entry

POST /v1/distribution_lists/{account_id}/destinations

Add a destination entry to the distribution list. A maximum of 10 destination entries per destination type. In terms of enterprise accounts, you can provide an Event Notifications destination that is from a different account than the distribution list account, provided these two accounts are from the same enterprise and the user has permission to manage the Event Notifications destinations on both accounts.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• notificationapi.accountemails.update
• resource-controller.instance.retrieve

Request

Request Body

AddDestinationPrototype

Response

201 - Successfully created the destination.

400 - Bad request - maximum limit reached or invalid parameters.

status

integer

HTTP status code.

trace

string

The unique identifier for tracing the request.

errors

array

Array of error details.

403 -

404 -

429 -

500 -

Get a destination entry

GET /v1/distribution_lists/{account_id}/destinations/{destination_id}

Retrieve a specific destination from the distribution list of the account.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• notificationapi.accountemails.view

Request

Response

200 - Successfully retrieved the destination.

400 -

403 -

404 -

429 -

500 -

Delete a destination entry

DELETE /v1/distribution_lists/{account_id}/destinations/{destination_id}

Remove a destination entry.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• notificationapi.accountemails.update
• resource-controller.instance.retrieve

Request

Response

204 - Successfully deleted the destination entry.

400 -

403 -

429 -

500 -

Test a destination entry

POST /v1/distribution_lists/{account_id}/destinations/{destination_id}/test

Send a test notification to a destination in the distribution list. This allows you to verify that the destination is properly configured and can receive notifications.

Authorization

To call this method, you must be assigned one or more IAM access roles that include the following action.

• notificationapi.accountemails.update

Request

Request Body

TestDestinationRequestBodyPrototype

Response

200 - Test notification sent successfully.

message

string

The status message that indicates the test result.

400 -

403 -

404 -

429 -

500 -

Get user notifications

GET /v1/notifications

Retrieve all notifications for the requested user.

Request

Path Parameters

Query Parameters

account_id

string

The IBM Cloud account ID. If not provided, the account ID from the bearer token will be used.

start

string

An opaque page token that specifies the resource to start the page on or after. If unspecified, the first page of results is returned.

limit

integer

The maximum number of items to return per page. If unspecified, a default limit of 50 is used.

Response

200 - Successfully retrieved notifications.

limit

integer

The maximum number of items returned in this response.

total_count

integer

The total number of notifications in the collection.

first

PaginationLink

A pagination link object containing the URL to a page.

previous

PaginationLinkWithToken

A pagination link object with a page token. Used for next, previous, and last page links.

next

PaginationLinkWithToken

A pagination link object with a page token. Used for next, previous, and last page links.

last

PaginationLinkWithToken

A pagination link object with a page token. Used for next, previous, and last page links.

notifications

array

Array of notification entries.

400 -

401 -

403 -

429 -

500 -

Get all communication preferences

GET /v1/notifications/{iam_id}/preferences

Retrieve all communication preferences of a user in an account.

Request

Response

200 - Successfully retrieved all user preferences for the given account.

incident_severity1

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity2

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity3

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity4

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_high

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_medium

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_low

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

announcements_major

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

announcements_minor

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

security_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

account_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_order

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_invoices

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_payments

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_subscriptions_and_promo_codes

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_spending_alerts

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

resourceactivity_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_review

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_reload_complete

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

400 -

403 -

404 -

429 -

500 -

Create communication preferences

POST /v1/notifications/{iam_id}/preferences

Create communication preferences for the specified account.

Request

Request Body

CreatePreferences

incident_severity1

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity2

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity3

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity4

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_high

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_medium

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_low

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

announcements_major

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

announcements_minor

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

security_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

account_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_order

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_invoices

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_payments

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_subscriptions_and_promo_codes

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_spending_alerts

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

resourceactivity_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_review

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_reload_complete

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_complete_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_complete_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

Response

201 - Successfully created communication preferences.

incident_severity1

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity2

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity3

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity4

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_high

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_medium

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_low

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

announcements_major

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

announcements_minor

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

security_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

account_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_order

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_invoices

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_payments

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_subscriptions_and_promo_codes

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_spending_alerts

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

resourceactivity_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_review

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_reload_complete

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

400 -

403 -

409 -

429 -

500 -

Replace communication preferences

PUT /v1/notifications/{iam_id}/preferences

Replace the communication preferences for the specified account.

Request

Request Body

CreatePreferences

incident_severity1

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity2

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity3

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

incident_severity4

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_high

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_medium

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

maintenance_low

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

channels

Required *

array

Array of communication channels for this preference.

updates

boolean

Whether to receive updates for this preference. Optional, defaults to false if not provided.

announcements_major

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

announcements_minor

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

security_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

account_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_order

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_invoices

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_payments

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_subscriptions_and_promo_codes

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

billing_and_usage_spending_alerts

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

resourceactivity_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_review

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

ordering_approved_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_reload_complete

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_complete_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

provisioning_complete_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

channels

Required *

array

Array of communication channels for this preference.

Response

200 - Successfully updated communication preferences.

incident_severity1

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity2

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity3

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

incident_severity4

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_high

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_medium

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

maintenance_low

PreferenceValueWithUpdates

Preference settings for notification types that support updates.

announcements_major

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

announcements_minor

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

security_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

account_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_order

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_invoices

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_payments

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_subscriptions_and_promo_codes

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

billing_and_usage_spending_alerts

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

resourceactivity_normal

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_review

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

ordering_approved_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_reload_complete

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_vsi

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

provisioning_complete_server

PreferenceValueWithoutUpdates

Preference settings for notification types that do not support updates.

400 -

403 -

404 -

429 -

500 -

Reset all preferences to their default values

DELETE /v1/notifications/{iam_id}/preferences

Delete all communication preferences for the specified account, and reset all preferences to their default values.

Request

Response

204 - Successfully deleted all communication preferences.

400 -

403 -

429 -

Get acknowledgement

GET /v1/notifications/acknowledgement

Retrieve the timestamp of the last acknowledgement by the user for a specific account..

Request

Response

200 - Successfully retrieved acknowledgement.

has_unread

boolean

Indicates whether the user has unread notifications.

last_acknowledged

integer

The timestamp of the last acknowledgement.

401 -

403 -

404 -

500 -

Update acknowledgement

PUT /v1/notifications/acknowledgement

Update the timestamp of the last acknowledgement by the user for a specific account.

Request

Request Body

AcknowledgementUpdate

last_acknowledged

Required *

integer

The timestamp of the last acknowledgement.

Response

200 - Successfully updated existing acknowledgement.

has_unread

boolean

Indicates whether the user has unread notifications.

last_acknowledged

integer

The timestamp of the last acknowledgement.

201 - Successfully created new acknowledgement.

has_unread

boolean

Indicates whether the user has unread notifications.

last_acknowledged

integer

The timestamp of the last acknowledgement.

400 -

401 -

403 -

429 -

500 -