Notifications

Emergency notifications are designed to support notification of front-desk personnel in the event that someone dials an emergency call from a multi-line telephone system (MLTS).

This facilitates:

• Meeting & directing emergency responders to the location of the emergency
• Dispatch of on-site emergency responders, who could be on-scene quicker than public responders.

Notification Types

Notification Types supported (up to 3 notifications to be sent for a single emergency call):

• SMS text message
• Voice phone call with text-to-speech
• Email notification
• HTTP Callback / Webhook

Relationships and Constraints Between Emergency Notification Concepts

• An emergency notification group may have from 1 to 3 emergency notification recipients.
• An emergency notification recipient may belong to at most 1 emergency notification group.
• An emergency endpoint may be associated with at most 1 emergency notification group.
• An emergency notification group may be associated with any number of emergency endpoints.

API Endpoint Overview

Base URL

https://dashboard.bandwidth.com/api/

Endpoints are case-sensitive. See full details in the API Reference

Emergency Notification Recipients

Endpoint	Description
/accounts/{accountId}/emergencyNotificationRecipients	Use the POST operation to create an emergency notification recipient. Use the GET operation with optional query parameters to fetch emergency notifications associated with the account.
/accounts/{accountId}/emergencyNotificationRecipients/{enrId}	Use the GET operation to fetch a specific emergency notification recipient by identifier. Use the PUT operation to replace an emergency notification recipient. Use the DELETE operation to remove an emergency notification recipient.

Emergency Notification Groups

Endpoint	Description
/accounts/{accountId}/emergencyNotificationGroupOrders	Use the POST operation to create an order to create, modify, or delete an emergency notification group. Use the GET operation with optional query parameters to fetch emergency notification group orders associated with the account.
/accounts/{accountId}/emergencyNotificationGroupOrders/{orderId}	Use the GET operation to fetch a specific emergency notification group order by identifier.
/accounts/{accountId}/emergencyNotificationGroups/{engId}	Use the GET operation to fetch a specific current emergency notification group by identifier.
/accounts/{accountId}/emergencyNotificationGroups	Use the GET operation with optional query parameters to fetch current emergency notification groups associated with the account.

Emergency Endpoint Associations to Emergency Notification Groups

Endpoint	Description
/accounts/{accountId}/emergencyNotificationEndpointOrders	Use the POST operation to create an order to add or remove emergency endpoint associations to an emergency notification group. Use the GET operation with optional query parameters to fetch emergency notification endpoint orders associated with the account.
/accounts/{accountId}/emergencyNotificationEndpointOrders/{orderId}	Use the GET operation to fetch a specific emergency notification endpoint order by identifier.
/tns/{tn}/tndetails	Use the GET operation to fetch information, including emergency endpoint associations to an emergency notification group for a specified telephone number.
/accounts/{accountId}/aeuis	Use the GET operation with optional query parameters to fetch information, including emergency endpoint associations to an emergency notification group for alternate caller identifiers associated with the account.
/accounts/{accountId}/aeuis/{acid}	Use the GET operation to fetch information, including emergency endpoint associations to an emergency notification group for a specified alternate caller identifier.

Key Terminology

Term	Description
Alternate Caller Identity (ACID)	See Alternate End-User Identity (AEUI).
Alternate End-User Identity (AEUI)	A unique alpha-numeric string which may be used as an alternative to using a telephone number to identify the applicable 911 end-user. An AEUI may have an End User name and valid street address, in addition to the optional association with an emergency notification group.
Callback	A mechanism to deliver an emergency notification in which an HTTPS URL is invoked with information about the emergency call. An emergency notification recipient can have a type of Callback to indicate that a web URL should be invoked to deliver the notification of an emergency call.
Callback Password	The password used to authenticate the sender of a Callback to the receiver of the Callback. When an emergency notification recipient is configured with type set to Callback, an HTTPS URL, callback password, and callback username are included in the configuration.
Callback Username	The username used to authenticate the sender of a Callback to the receiver of the Callback. When an emergency notification recipient is configured with type set to Callback, an HTTPS URL, callback password, and callback username are included in the configuration.
Callback URL	The HTTPS URL used as the target of an emergency notification recipient with type Callback. When an emergency notification recipient is configured with type set to Callback, an HTTPS URL, callback password, and callback username are included in the configuration.
Date Formats	Where displayed or used for filtering order histories, use the format YYYY-MM-DDTHH:MM:SS.mmmmX, where if "X" is used for timezone information. For UTC, "X" is replaced with "Z". For other timezones, "X" is replaced with a positive or negative UTC offset. For example, a date and time specified in U.S. EDT would look like 2020-04-01T15:40:32.243-05:00. A date and time specified in U.S. EST would look like 2019-12-17T04:55:21.099-04:00. A date and time specified in Japan standard time would look like 2020-04-01T15:48:29.798+09:00. If the timezone information is omitted, UTC is assumed. If the time is omitted, time 00:00:00.000 is assumed.
Emergency Call	If an emergency endpoint is associated with an emergency notification group, and an emergency call is originated from that endpoint, notifications are sent according to the emergency notification recipients configured for the emergency notification group.
Emergency Endpoint	An identifier associated with the originator of an emergency call. An emergency endpoint may be a telephone number or an AEUI. An emergency endpoint must be configured with an emergency location, including a valid street address. An emergency endpoint may be associated with one emergency notification group.
Emergency Endpoint AEUI	An emergency endpoint defined as an AEUI.
Emergency Endpoint TN	An emergency endpoint defined as a telephone number (TN).
Emergency Notification Endpoint Order	When an emergency endpoint is associated with an emergency notification group, that association is configured by submitting an order. The "order" provides a record of what was configured, when, and by whom. It also allows you to do other things while the order is being fulfilled. For example, an order to associate 10,000 emergency endpoints to an emergency notification group may take a couple of minutes to complete. If necessary for trouble-shooting, you may query the order history in a number of ways to find out when an endpoint was added to or removed from a group.
Emergency Notification Group	A container for a set of emergency endpoints that should all trigger the same set of emergency notifications if one of them places an emergency call. An emergency notification group may have from one to three emergency notification recipients of any type. For example, a group could have two email recipients and one SMS recipient. Any number of emergency endpoints may be associated with an emergency notification group.
Emergency Notification Group Order	When an emergency notification group is configured, it is done by submitting an order. The "order" provides a record of what was configured, when, and by whom. It also allows you to do other things while the order is being fulfilled. For example, if you add a new emergency notification recipient to an emergency notification group that has 10,000 emergency endpoints associated, it may take a couple of minutes to process the order. If necessary for trouble-shooting, you may query the order history in a number of ways to find out when a group was added, updated, or removed.
Emergency Notification Recipient	Defines the recipient of an emergency notification by specifying who should be notified and how that notification should be delivered. An emergency notification recipient has a description, a type, and a target. The type can be one of EMAIL, SMS, TTS, or CALLBACK. The target goes along with the type. For example, if the type is EMAIL, then the target is an email address. If the type is SMS, the target is a telephone number capable of receiving texts. If the type is TTS, the target is a telephone number. If type is CALLBACK, the target is an HTTPS URL that specifies the callback server. When type is CALLBACK, a Username and Password are also configured to authenticate the call to the callback server. An emergency notification recipient may be associated with one emergency notification group.
Notification Type	The mechanism used to deliver a emergency notification. Emergency notifications may be delivered by email, text, voice call (using text-to-speech), or a web callback. See Emergency Notification Recipient for more details.
Short Message Service (SMS)	A means of delivering text messages to an SMS enabled device like a smart phone. An emergency notification recipient can have a type of SMS, meaning that a text should be sent to the configured telephone number if an emergency call is placed by an emergency endpoint associated with the emergency notification group that uses that recipient.
Text To Speech (TTS)	A means of delivering a voice call to notify a recipient of an emergency call. An emergency notification recipient can have a type of TTS, meaning that a text-to-speech voice call should be placed to the configured telephone number if an emergency call is placed by an emergency endpoint associated with the emergency notification group that uses that recipient.