Note: Rewritten to reflect the actual implementation using Bandwidth Universal Platform v2 API (not the legacy DLR Dashboard API referenced in the original use cases). See FR-581 comment for details.

User Stories

• As a business owner, I want my company's emergency calls to include the correct business phone number and the accurate location of the employee in need so that emergency services can quickly find or contact them.
• As a CSP, I want to route emergency calls through Bandwidth to ensure compliance with US regulations.

Example of use

• CSP enables Emergency service with Bandwidth provider on a product in PortaSwitch.
• Enterprise customer sets address on their customer record, customer site, or account — this address becomes the emergency location.
• PortaSwitch provisions the emergency endpoint in Bandwidth via iPaaS adapter (address + phone number sent in a single API call).
• Bandwidth validates and standardizes the address, creates an endpoint, and returns an endpoint ID stored as provider_endpoint in PortaSwitch.
• In an actual emergency, a live 911 call is routed to Bandwidth with a Geolocation header (Location by Reference) pointing to the provisioned endpoint, ensuring that the PSAP (Public Safety Answering Point) receives accurate, standardized dispatch details.

Business model

Cloud PBX / Call Center / UCaaS / SIP trunking

Technology

• API Integration: PortaSwitch communicates with Bandwidth via a three-tier architecture:
• PortaSwitch REST API → iPaaS E911 adapter (Add-on Mart) → Bandwidth Universal Platform v2 API (POST /api/v2/accounts/{id}/emergency/endpoints)
• Address validation and endpoint creation happen in a single call (no separate validation step)
• The adapter endpoint: POST /e911/e911-bandwidth:addEmergencyEndpoint
• SIP Signaling: PortaSwitch enriches SIP INVITE messages to include:
• CallbackNumber: A NANPA-compliant number (e.g., "1321551234") from the From or P-Asserted-Identity headers.
• Geolocation Data: Provided via Location by Reference — a URL constructed from the provider_endpoint attribute value: Geolocation: <https://emergency.bandwidth.com/locations/{bw_account_id}/{endpoint_id}>

Current Solution

Currently, PortaSwitch is integrated with Intrado, but there is no integration with Bandwidth.

Stakeholders and their benefits

Use Cases

Use Case #1: Emergency Location Provisioning and Management

Preconditions:

• PortaSwitch is configured with Bandwidth E911 iPaaS adapter (Add-on Mart module subscribed and configured)
• Configurator: EmergencyModule->Bandwidth_Provider_Enabled is ON
• Product has Emergency service = Bandwidth enabled
• There is (Sub)Customer "Helpdesk 365" with account 1321551234 (extension 1000)
• Address cascade priority: account → customer site → customer (high → low)

Roles: PortaSwitch, Bandwidth, Customer, End user, National call center (NCC), Public-safety answering point (PSAP), Communication service provider (CSP)

Use scenario #1.1: Provisioning a Valid Emergency Location

• Customer updates their address in PortaSwitch (via self-care portal or API):

• PortaSwitch sends a request to Bandwidth via iPaaS adapter (addEmergencyEndpoint) to create an emergency endpoint with the customer's address
• Bandwidth validates the address, creates the endpoint, and returns an endpoint ID
• PortaSwitch stores the endpoint ID in the provider_endpoint service attribute on the customer
• The endpoint is visible on the Bandwidth side with standardized address: 900 MAIN CAMPUS DR, STE 500, RALEIGH, NC 27606-5177, US
• All accounts use the same endpoint id while making emergency calls

Use scenario #1.2: Provisioning an Invalid Emergency Location (alternative to #1.1)

• same beginning as in #1.1
• Customer updates their address to an invalid one (e.g., address that cannot be standardized by Bandwidth)
• PortaSwitch sends a request to Bandwidth via iPaaS adapter
• Bandwidth rejects the address — returns an error
• PortaSwitch rejects the address update and returns an error to the customer
• The previous provider_endpoint (if any) remains unchanged
• Customer sees that the address update was rejected

Use scenario #1.3: Assigning a Valid Emergency Location to a Phone Line (via Customer Site)

• continued after #1.1
• Customer creates a customer site "CarryOffice" with address:

• Customer assigns account 1321551234 (extension 1000) to the "CarryOffice" site
• PortaSwitch creates a new emergency endpoint with the site's address (site address overrides customer address in the cascade)
• Bandwidth endpoint now shows CarryOffice address: 600 CHATHAM ST, CARY, NC 27513, US
• All assigned to the site accounts use the newly created endpoint id while making an emergency call

Use scenario #1.4: Restrict Invalid Emergency Location for a Phone Line (alternative to #1.3)

• continued after #1.3
• Customer creates another site "BadOffice" with an invalid address
• Customer/End user attempts to reassign account 1321551234 to "BadOffice" site
• PortaSwitch attempts to create a new endpoint with BadOffice address via Bandwidth
• Bandwidth rejects the invalid address
• PortaSwitch rejects the account reassignment — the account remains assigned to "CarryOffice" site
• The provider_endpoint remains unchanged (still points to CarryOffice endpoint)
• If account 1321551234 makes a call to 911 without a valid emergency location:
• PortaSwitch still sends the emergency call to Bandwidth
• National call center handles the call, asks the end user for their address
• NCC forwards the call to the appropriate PSAP
• Bandwidth notifies CSP via email about the unregistered 911 call

Use scenario #1.5: Deleting Unused Emergency Locations

• continued after #1.3 (account is assigned to "CarryOffice" site)
• Customer moves account 1321551234 out of the "CarryOffice" site (unassigns from site)
• Account falls back to customer-level address (NCOffice) in the cascade — PortaSwitch reuses the endpoint with the customer's address
• Customer deletes the "CarryOffice" site (which is now unused — no accounts assigned to it)
• PortaSwitch deletes the site's emergency endpoint from Bandwidth (per BA_REQ10.1)
• The customer-level endpoint (NCOffice) is not affected

Use scenario #1.6a: Passing an Emergency Location on a 911 Call (Location by Value, PIDF-LO)

Skipped for this release — only Location by Reference is implemented.

Use scenario #1.6b: Passing an Emergency Location on a 911 Call (Location by Reference, alternative to #1.6a)

• End user makes a call to 911 (or 933 test number) using extension 1000
• PortaSwitch sends the emergency call to Bandwidth with a Geolocation header constructed from the provider_endpoint attribute:

INVITE sip:911@emergencyDLR2;transport=tcp SIP/2.0
Via: SIP/2.0/TCP 1.1.1.1:5060;branch=z9hG4bKxxxxx
Call-ID: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Contact: <sip:1321551234@1.1.1.1:5060>
CSeq: 102 INVITE
From: <sip:1321551234@1.1.1.1>;tag=xxxxx
To: <sip:911@emergencyDLR2>
Max-Forwards: 20
Priority: emergency
User-Agent: xxxxxx
Geolocation: <https://emergency.bandwidth.com/locations/{bw_account_id}/{endpoint_id}>
Geolocation-Routing: no
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, NOTIFY, REGISTER, SUBSCRIBE, REFER, PUBLISH, UPDATE, MESSAGE
Accept: application/sdp, application/pidf+xml
Content-Type: application/sdp
Content-Length: 275
v=0
o=- 659841 659841 IN IP4 xxx.xxx.xxx.xxx
s=Talk
c=IN IP4 xxx.xxx.xxx.xxx
t=0 0
m=audio 16006 RTP/AVP 0 101
a=rtpmap:0 PCMU/8000
a=rtpmap:101 telephone-event/8000
a=fmtp:101 0-16
a=ptime:20
a=maxptime:150
a=sendrecv

Where {bw_account_id}/{endpoint_id} is the value of the provider_endpoint attribute (e.g., 555555/202369122819078578). The base URL https://emergency.bandwidth.com/locations/ is configured in PortaSIP Configurator.

• Bandwidth validates the geolocation and callback details and routes the call to the appropriate local PSAP.

Use scenario #1.7: Assigning Another Valid Emergency Location to a Phone Line

• continued after #1.5 (account has customer-level NCOffice address, no site assigned)
• Customer updates the account's own address to CarryOffice (a case when an end-user works remotely):

• PortaSwitch creates a new endpoint with account-level address (account address has highest priority in cascade)
• The old customer-level endpoint is not deleted (per BA_REQ10.2)
• The provider_endpoint is updated with the new endpoint ID
• Bandwidth endpoint now shows CarryOffice address for phone number 1321551234

Use scenario #1.8: Deleting Phone Lines

• Customer terminates account 1321551234
• PortaSwitch deletes the account's emergency endpoint from Bandwidth (per BA_REQ10.0)
• Bandwidth deletes the corresponding endpoint
• The customer "Helpdesk 365" and its address are not deleted
• Any customer-level or site-level emergency endpoints are not affected by the account termination

Non-functional Requirements

• N/A

Peculiarities

• The implementation uses Bandwidth Universal Platform v2 API (/api/v2/accounts/{id}/emergency/endpoints), not the legacy DLR Dashboard API referenced in the original use cases. See FR-581 comment.
• Emergency location in PortaSwitch is the address of the entity (customer, customer site, or account) — there are no separate "emergency location" objects.
• Address cascade: account address → customer site address → customer address (high → low priority).
• provider_endpoint attribute format: "{bw_account_id}/{endpoint_id}" — stored at the entity level where the address resides.
• The CSP does not receive incoming 911 calls with location data.
• The CSP gets fined for 911 calls with invalid addresses.
• Only Location by Reference is supported in this release (1.6a / PIDF-LO is skipped).

Performance / Clustering, Geo Redundancy / Dual-Version, Porter / Call Control API

• The use scenarios must be supported in the Standalone and Dual Version modes.

ESPF / Monitoring

N/A