Skip to main content

Manage E911 orders

The E911Orders endpoint resource represents the requests made to the Bandwidth Dashboard API to add or otherwise manage a request to associate a postal address with an endpoint (a telephone number, ACID (alternate caller identifier), or some other unique identifier. This API allows the creation and observation of a "E911" work order that causes an update of a address information in a network database.

The E911 order processing model is consistent with the overall model of creating an order or request with the initial POST, and then checking on the status of that order using callbacks and / or GET while that order progresses through the various steps in the process.

The E911 order supports several 911 use cases:#

  1. CONVENTIONAL E911: Telephone number/address combination. For UC Trunking and most applicable wholesale customers, this method associates a telephone number in the customer’s Bandwidth Dashboard API TN inventory to a postal address. Caller name can also be specified in the request. At 911 call time, the address that is associated with the telephone number in the SIP 'from' header will be seen by the Public Safety Answering Point (PSAP).

  2. PIDF-LO (Presence Information Data Format-Location Object or Dynamic Location Routing) Endpoints and Addresses: For customers utilizing Bandwidth’s Dynamic Routing capability, addresses are first added to an "address pool", then endpoints are provisioned using one of the addresses as a default for taxation purposes. Each endpoint is represented by an Alternate End User Identifier consisting of a unique identifier (could be TN, ACID, or other identifier), callback number and caller name (if not being passed in at 911 call time), and preferred language (French or English, with English as the default). At 911 call time, the customer can pass any address in the SIP header of the call and the sip 'from' header will contain the identifier of the endpoint. If the address in the call matches an address in the address pool, then the call is routed to the PSAP. Otherwise, the call is routed to an Emergency Call Center.

  3. SIMPLE AEUI: This is similar to telephone number/address combination in that there is a 1 to 1 mapping between endpoint and address. Each endpoint is represented by an Alternate End User Identifier(AEUI) consisting of a unique identifier and callback number. At 911 call time, the endpoint identifier is passed in the SIP from header and the address that is associated with that endpoint will be seen by the PSAP.

    The states that the order may reside in are RECEIVED, PROCESSING, COMPLETE, PARTIAL, FAILED, ADJUSTED_COMPLETE, and ADJUSTED_PARTIAL. "ADJUSTED" indicates that the provisioning was successful, but that the street address was subtly changed to reflect a geocodable address. As with other order types, PARTIAL indicates that there were some errors detected, but that all elements of the order that could be processed were processed. In this case, the order record will need to be examined to determine the items that failed.

The key data elements in the submission are as follows.#

ParameterDescription
TelephoneNumbersA list of telephone numbers you need link to the street address
CallerNameCallerName that will be linked to TNs. This field is required in the case of a new address assignment
AddressThis field is required in the case of a new address assignment. Inner fields: HousePrefix, HouseNumber, HouseSuffix, PreDirectional, StreetName, StreetSuffix, PostDirectional, AddressLine2, City, StateCode, Zip, PlusFour. Streetname, City, and State are required. House Number is currently required, although this enforcement may be relaxed in the future. Depending on the type of E911 service, the Location ID may be updated by the Bandwidth Dashboard API
DeleteTNSpecificE911AddressCan be true or false. If value is true then Address and CallerName should not be specified
AlternateEndUserIdentifiersA list of AEUIs acts as a replacement for the list of telephone numbers. It replaces the TelephoneNumbers and AdditionalAddress payload element. If ACID exists in external system it will be updated with given values
AdditionalAddressesA list of Address sections. This address information for all potential endpoints which will be provisioned to the Bandwidth 911 system. At call time, the customer will submit this address information within the SIP header and, if a match is determined, the call will be routed to the PSAP nearest to that address. Otherwise, the call will be routed to an ECC. These Address sections will be the same in format to the Address section in the top-level of the E911Order payload. It replaces the TelephoneNumbers and AlternateEndUserIdentifiers payload element
CustomerOrderIdThe Customer Order ID is an ID assigned by the account owner to provide a reference number for the Order. The element is optional. Only alphanumeric values, dashes and spaces are allowed. Max length is 40 characters

Examples of POST requests:#

CONVENTIONAL E911. TN/Address-provisioning order#

TN/Address-provisioning order. TelephoneNumbers, TelephoneNumber, and Address are required.

<E911Order>
<TelephoneNumbers>
<TelephoneNumber>9706542332</TelephoneNumber>
<TelephoneNumber>9706542333</TelephoneNumber>
</TelephoneNumbers>
<CallerName>OptionalCallerName</CallerName>
<Address>
<HouseNumber>915</HouseNumber>
<HouseSuffix/>
<PreDirectional/>
<StreetName>Elm</StreetName>
<StreetSuffix>Ave</StreetSuffix>
<PostDirectional/>
<AddressLine2/>
<City>Carpinteria</City>
<StateCode>CA</StateCode>
<Zip>93013</Zip>
<PlusFour/>
<County/>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
</Address>
</E911Order>

CONVENTIONAL E911. TN/address-deletion order#

TelephoneNumbers and TelephoneNumber are required. DeleteTNSpecificE911Address is required and must be set to 'true'.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<TelephoneNumbers>
<TelephoneNumber>9706542332</TelephoneNumber>
<TelephoneNumber>9706542333</TelephoneNumber>
</TelephoneNumbers>
<DeleteTNSpecificE911Address>true</DeleteTNSpecificE911Address>
</E911Order>

PIDF-LO. PIDF-LO AEUI endpoint-provisioning order with additional address provisioning and without pre-defined location id#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, Address, and Identifier are required. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters. PIDFLOEnabled is required and must be 'true'. Default value of PreferredLanguage is 'en'.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<Address>
<HouseNumber>901</HouseNumber>
<StreetName>MAIN CAMPUS</StreetName>
<StreetSuffix>DR</StreetSuffix>
<City>RALEIGH</City>
<StateCode>NC</StateCode>
<Zip>27606</Zip>
<PlusFour>5244</PlusFour>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<AddressType>E911</AddressType>
</Address>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<CallerName>OptionalCallerName</CallerName>
<CallbackNumber>9706542333</CallbackNumber>
<Identifier>blep123</Identifier>
<PIDFLOEnabled>true</PIDFLOEnabled>
<PreferredLanguage>en</PreferredLanguage>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
</E911Order>

PIDF-LO. PIDF-LO AEUI endpoint-provisioning order with additional address provisioning and with pre-defined location id#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, Address, and Identifier are required. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters. PIDFLOEnabled is required and must be 'true'. Default value of PreferredLanguage is 'en'.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<Address>
<LocationId>Some32CharacterOrLessString</LocationId>
<HouseNumber>901</HouseNumber>
<StreetName>MAIN CAMPUS</StreetName>
<StreetSuffix>DR</StreetSuffix>
<City>RALEIGH</City>
<StateCode>NC</StateCode>
<Zip>27606</Zip>
<PlusFour>5244</PlusFour>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<AddressType>E911</AddressType>
</Address>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<CallerName>OptionalCallerName</CallerName>
<CallbackNumber>9706542333</CallbackNumber>
<Identifier>blep123</Identifier>
<PIDFLOEnabled>true</PIDFLOEnabled>
<PreferredLanguage>en</PreferredLanguage>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
</E911Order>

PIDF-LO. PIDF-LO AEUI endpoint-provisioning order with provisioned location id#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, LocationId, and Identifier are required. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters. PIDFLOEnabled is required and must be 'true'. Default value of PreferredLanguage is 'en'.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<CallerName>OptionalCallerName</CallerName>
<LocationId>Some32CharacterOrLessString</LocationId>
<CallbackNumber>9706542333</CallbackNumber>
<Identifier>blep123</Identifier>
<PIDFLOEnabled>true</PIDFLOEnabled>
<PreferredLanguage>en</PreferredLanguage>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
</E911Order>

PIDF-LO and SIMPLE AEUI. Mixed PIDF-LO AEUI and Non-PIDF-LO AEUI endpoint-provisioning order#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, Address, and Identifier are required. Default value of PreferredLanguage is 'en'. Non-PIDF-LO: CallbackNumber is required. Identifier can only contain alphanumeric characters and must be between 6 and 30 characters. PIDF-LO: PIDFLOEnabled is required and must be 'true'. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<CallerName>OptionalCallerName</CallerName>
<Address>
<LocationId>Some32CharacterOrLessString</LocationId>
<HouseNumber>901</HouseNumber>
<StreetName>MAIN CAMPUS</StreetName>
<StreetSuffix>DR</StreetSuffix>
<City>RALEIGH</City>
<StateCode>NC</StateCode>
<Zip>27606</Zip>
<PlusFour>5244</PlusFour>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<AddressType>E911</AddressType>
</Address>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<CallerName>OptionalCallerName</CallerName>
<LocationId>Some32CharacterOrLessString</LocationId>
<CallbackNumber>9706542333</CallbackNumber>
<Identifier>blep123</Identifier>
<PIDFLOEnabled>true</PIDFLOEnabled>
<PreferredLanguage>en</PreferredLanguage>
</AlternateEndUserIdentifier>
<AlternateEndUserIdentifier>
<CallbackNumber>9706542334</CallbackNumber>
<Identifier>blepblop</Identifier>
<PIDFLOEnabled>false</PIDFLOEnabled>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
</E911Order>

PIDF-LO and SIMPLE AEUI. PIDF-LO and Non-PIDF-LO endpoint-deletion order#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, and Identifier are required. DeleteTNSpecificE911Address is required and must be 'true'. Non-PIDF-LO: CallbackNumber is required. Identifier can only contain alphanumeric characters 6 and 30 characters. PIDF-LO: PIDFLOEnabled is required and must be 'true'. Identifier can only contain alphanumeric characters and must be between 1 and 30 characters.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<Identifier>identifier</Identifier>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
<DeleteTNSpecificE911Address>true</DeleteTNSpecificE911Address>
</E911Order>

PIDF-LO. PIDF-LO address-provisioning order#

AdditionalAddresses and Address are required.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<AdditionalAddresses>
<Address>
<LocationId>Some32CharacterOrLessString</LocationId>
<HouseNumber>901</HouseNumber>
<StreetName>MAIN CAMPUS</StreetName>
<StreetSuffix>DR</StreetSuffix>
<City>RALEIGH</City>
<StateCode>NC</StateCode>
<Zip>27606</Zip>
<PlusFour>5244</PlusFour>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<AddressType>E911</AddressType>
</Address>
<Address>
<LocationId>Some32CharacterOrLessString</LocationId>
<HouseNumber>645</HouseNumber>
<PreDirectional>E</PreDirectional>
<StreetName>MANCHESTER</StreetName>
<StreetSuffix>AVE</StreetSuffix>
<City>LOS ANGELES</City>
<StateCode>United States</StateCode>
<Zip>90001</Zip>
<Country>United States</Country>
</Address>
</AdditionalAddresses>
</E911Order>

PIDF-LO. PIDF-LO address-editing order#

Address and LocationId are required. Allows a user to update all address fields except PlusFour and Country.

<E911Order>
<AdditionalAddresses>
<Address>
<HouseNumber>645</HouseNumber>
<PreDirectional>E</PreDirectional>
<HouseSuffix>1/2</HouseSuffix>
<PostDirectional>S</PostDirectional>
<StreetName>Manchester</StreetName>
<StreetSuffix>AVE</StreetSuffix>
<AddressLine2>test address line 2</AddressLine2>
<City>Los Angeles</City>
<StateCode>CA</StateCode>
<Zip>90001</Zip>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<LocationId>Some32CharacterOrLessString</LocationId>
</Address>
</AdditionalAddresses>
</E911Order>

PIDF-LO. PIDF-LO address-deletion order#

AdditionalAddresses, Address, and LocationId are required. DeleteTNSpecificE911Address is required and must be 'true'.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<AdditionalAddresses>
<Address>
<LocationId>Some32CharacterOrLessString1</LocationId>
</Address>
<Address>
<LocationId>Some32CharacterOrLessString1</LocationId>
</Address>
</AdditionalAddresses>
<DeleteTNSpecificE911Address>true</DeleteTNSpecificE911Address>
</E911Order>

SIMPLE AEUI. Non-PIDF-LO endpoint-provisioning order#

AlternateEndUserIdentifiers, AlternateEndUserIdentifier, Address, CallbackNumber, and Identifier are required Identifier can only contain alphanumeric characters, must contain at least one letter, and must be between 6 and 30 characters.

<E911Order>
<CustomerOrderId>CustomOrderId1</CustomerOrderId>
<CallerName>OptionalCallerName</CallerName>
<Address>
<LocationId>Some32CharacterOrLessString</LocationId>
<HouseNumber>901</HouseNumber>
<StreetName>MAIN CAMPUS</StreetName>
<StreetSuffix>DR</StreetSuffix>
<City>RALEIGH</City>
<StateCode>NC</StateCode>
<Zip>27606</Zip>
<PlusFour>5244</PlusFour>
<Country>United States</Country>
<Latitude>35.848359</Latitude>
<Longitude>-75.000000</Longitude>
<AddressType>E911</AddressType>
</Address>
<AlternateEndUserIdentifiers>
<AlternateEndUserIdentifier>
<CallbackNumber>9706542333</CallbackNumber>
<Identifier>abc123</Identifier>
<PIDFLOEnabled>false</PIDFLOEnabled>
</AlternateEndUserIdentifier>
</AlternateEndUserIdentifiers>
</E911Order>