Current version of the BRS was written with a focus on Bandwidth API v1 which turned out to be a legacy DLR Dashboard API. Details can be found here. However, implementation itself and test plan for QA verification are based on Bandwidth API v2. AI based adaptation of current page for APIv2 can be found here.
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
- Enterprise customer submits their emergency location to Bandwidth - one of the leading E911 services provider in the US and Canada.
- Bandwidth validates the submitted emergency locations.
- Enterprise customer associates their phone lines with the validated emergency locations and the callback number (NANPA-valid phone number at which the 911 caller can be reached)
- In an actual emergency, a live 911 call is routed to Bandwidth and signals the emergency location associated with the caller, 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 leverages Bandwidth’s E911 Dynamic Location Routing API to provision locations and register endpoints immediately upon user action.
- SIP Signaling: PortaSwitch enriches SIP INVITE messages to include:
- CallbackNumber: A separate NANPA‑compliant number (e.g., “1321551234”) where the caller can be reached (From or P-Asserted-Identity headers).
- Geolocation Data: Provided via Location by Value with PIDF‑LO or Location by Reference.
Current Solution
Currently, PortaSwitch is integrated with Intrado, but there is no integration with Bandwidth
Stakeholders and their benefits
| Benefit / Stakeholders | More Comfort | Safety | Tighter Control | Regulatory Requirement |
|---|---|---|---|---|
| CSP |  | |||
| Customers | | | | |
| Resellers / distributors | | |||
| PSAP/Emergency services | | |||
| End user | |
Use Cases
Use Case #1: Real-Time Provisioning of Emergency Location
Preconditions:
- PortaSwitch is configured to communicate with Bandwidth via API and SIP
- Customers and/or End users have access to the self-care portals that communicate with PortaSwitch via API
- There is (Sub)Customer "Helpdesk 365" with phone number 1321551234
Roles: PortaSwitch, Bandwidth, Customer, End user, National call center (NCC), Public-safety answering point (PSAP), Communication service provider (CSP)
Use scenario #1.1: Provisioning of a Valid Emergency Location
- Customer logs in to the self-care portal and adds an emergency location
| Geolocation ID | NCOffice |
|---|---|
| State / Province* | North Carolina |
| City* | Raleigh |
| Street number* | 900 |
| Street name* | Main Campus Drive |
| Address line 2 | Suite 500 |
| ZIP / Postal code* | 27606 |
| ZIP plus 4 |
- PortaSwitch sends a request to Bandwidth to validate a location
- Bandwidth validates the submitted location
- PortaSwitch sends a provisioning request to Bandwidth to create a location
- Bandwidth standardizes it, and returns the standardized location details: 900 MAIN CAMPUS DR, STE 500, RALEIGH, NC 27606-5177, US
Use scenario #1.2: Provisioning of a Invalid Emergency Locations (alternative to #1.1)
- same beginning as in #1.1
- PortaSwitch sends a request to Bandwidth to validate a location
- Bandwidth does not validate the submitted location and returns an error (for example, if the location cannot be standardized) to PortaSwitch
- Customer sees that the submitted emergency location as invalid/unverified
Use scenario #1.3: Assigning a Valid Emergency Location to a Phone Line
- continued after #1.1
- Customer creates extension 1000
- Customer/End user assigns "NCOffice" emergency location to extension 1000
- Customer/End user defines 1321551234 as the number that the emergency service can use to contact the caller in emergency situations
- PortaSwitch requests Bandwidth to associate 1321551234 with "NCOffice" emergency location
- Bandwidth creates the endpoint and associates it with the existing location
Use scenario #1.4: Restrict Invalid Emergency Location for a Phone Line (alternative to #1.3)
- continued after #1.2
- Customer creates extension 1000
- Customer/End user cannot assign "NCOffice" emergency location to extension 1000 as it is invalid/unverified
- Later on, end user makes a call to 911 using extension 1000
- Even though this extension is not associated with any emergency location, PortaSwitch sends the emergency call to Bandwidth
- National call center still handles the call, they will just have to ask for the address from the end user
- Depending on the address provided by the end user, National call center forwards the call to the appropriate Public-safety answering point (PSAP)
- Bandwidth notifies Communication service provider (CSP) via email about the unregistered 911 call
- CSP investigates if it was an issue with their own installation team or something else
Use scenario #1.5: Deleting Unused Emergency Locations
- Customer creates a new emergency location as in #1.1
- Customer deletes this emergency location as it is not assigned to any phone line
- PortaSwitch requests Bandwidth to delete the unused emergency location
Use scenario #1.6a: Passing an Emergency Location on a 911 Call (Location by Value, PIDF-LO)
- End users make a call to 911 using extension 1000
- PortaSwitch sends the emergency call to Bandwidth:
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: <cid:pidf-attachment@abcprovider.com>
Geolocation-Routing: yes
Allow: INVITE, ACK, BYE, CANCEL, OPTIONS, NOTIFY, REGISTER, SUBSCRIBE, REFER, PUBLISH, UPDATE, MESSAGE
Content-Type: multipart/mixed;boundary=Boundary_102345
Content-Length: 1293
--Boundary_102345
Content-Type: application/sdp
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
--Boundary_102345
Content-Type: application/pidf+xml
Content-ID: <pidf-attachment@abcprovider.com>
<?xml version="1.0" encoding="UTF-8"?>
<presence
xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:gml="http://www.opengis.net/gml"
xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
entity="pres:9zdRwdQqYV88tX@123.123.123.123">
<dm:device id="target123-1">
<gp:geopriv>
<gp:location-info>
<ca:civicAddress>
<ca:country>us</ca:country>
<ca:HNO>900</ca:HNO>
<ca:RD>MAIN CAMPUS</ca:RD>
<ca:STS>DR</ca:STS>
<ca:A1>NC</ca:A1>
<ca:A3>RALEIGH</ca:A3>
<ca:LOC>STE 500</ca:LOC>
<ca:PC>27606</ca:PC>
</ca:civicAddress>
</gp:location-info>
</gp:geopriv>
</dm:device>
</presence>
--boundary_102345--
- Bandwidth validates the geolocation and callback details and routes the call to the appropriate local PSAP.
Use scenario #1.6b: Passing an Emergency Location on a 911 Call (Location by Reference, alternative #1.6a)
- End users makes a call to 911 using extension 1000
- PortaSwitch sends the emergency call to Bandwidth:
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/123456/NCOffice> 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
- 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
- Customer adds a new emergency location
| Geolocation ID | CarryOffice |
|---|---|
| State / Province* | North Carolina |
| City* | Cary |
| Street number* | 600 |
| Street name* | Chatham Street |
| Address line 2 | |
| ZIP / Postal code* | 27513 |
| ZIP plus 4 |
- PortaSwitch sends requests to Bandwidth to validate and create a validated location just like in #1.1
- Bandwidth validates the submitted location, standardizes it, and returns the standardized location details: 600 CHATHAM ST CARY, NC 27513, US
- End user with extension 1000 is going to move to the new office in Cary
- Customer/End user opens extension 1000 and associates extension 1000 with "CarryOffice" location
- Extension 1000 registers in the network and makes an emergency call to 911
- PortaSwitch sends the emergency call to Bandwidth with the new emergency location for 1321551234:
...
--Boundary_106789
Content-Type: application/pidf+xml
Content-ID: <pidf-attachment@abcprovider.com>
<?xml version="1.0" encoding="UTF-8"?>
<presence
xmlns="urn:ietf:params:xml:ns:pidf"
xmlns:gp="urn:ietf:params:xml:ns:pidf:geopriv10"
xmlns:gbp="urn:ietf:params:xml:ns:pidf:geopriv10:basicPolicy"
xmlns:ca="urn:ietf:params:xml:ns:pidf:geopriv10:civicAddr"
xmlns:gml="http://www.opengis.net/gml"
xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
entity="pres:9zdRwdQqYV88tX@123.123.123.123">
<dm:device id="target123-1">
<gp:geopriv>
<gp:location-info>
<ca:civicAddress>
<ca:country>us</ca:country>
<ca:HNO>600</ca:HNO>
<ca:RD>CHATHAM</ca:RD>
<ca:STS>ST</ca:STS>
<ca:A1>NC</ca:A1>
<ca:A3>CARY</ca:A3>
<ca:PC>27513</ca:PC>
</ca:civicAddress>
</gp:location-info>
</gp:geopriv>
</dm:device>
</presence>
--Boundary_106789--
- Bandwidth validates the geolocation and callback details and routes the call to the appropriate local PSAP.
Use scenario #1.8: Deleting Phone Lines
- Customer deletes extension 1000
- PortaSwitch sends a request to Bandwidth to delete the endpoint
- Bandwidth deletes the corresponding endpoint
- The emergency location previously associated with extension 1000 is not deleted for (Sub)Customer "Helpdesk 365"
Non-functional Requirements
- N/A
Peculiarities
- Adding the PIDF attachment to the SIP INVITE is likely to make the SIP INVITE too large to fit into a UDP packet, so this will need to also support SIP packets over TCP in order to avoid packet fragmentation.
- Currently used emergency locations contain: country, HNO, PRD, RD, STS, A1, A3, LOC, PC - see Provisioning limits and restrictions
- Currently, the CSP passes locations in PIDF-LO (Location by Value), but it's worth considering if implementation of Location by Reference is simpler/requires less resources
- The CSP does not receive incoming 911 calls with location data
- The CSP gets fined for 911 calls with invalid addresses
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