Emergency Calling - Dynamic e911

Telnyx's Dynamic e911, also known as e911 with Dynamic Location Routing, provides accurate location information at the time of a 911 call using PIDF-LO (Presence Information Data Format-Location Object), which will allow emergency responders to quickly reach the person placing the call.

In this guide you'll learn how to set up Dynamic Location Routing for emergency calling in just a few steps.


Part 1: Configuration using Emergency API

When setting up caller information in Dynamic Location Routing (DLR), addresses need to be provisioned beforehand. Dynamic Emergency Addresses are assumed to be used whenever 911 calls are originated. Multiple Emergency Addresses can be configured at account level.

Once provisioned, each address has an associated location ID (Geolocation ID) that is unique across your account. The location IDs can be used in subsequent API requests to configure additional endpoints. These endpoints represent the calling party and are provisioned using a set of information representing an extension to user identification information.

Telnyx provides two Emergency API endpoints for DLR configuration:

  1. https://api.telnyx.com/v2/dynamic_emergency_addresses

Dynamic Emergency Address is used to create a customer location physical address, where a e911 call may originate from. This address is normally associated with office locations, business locations, etc.

  1. https://api.telnyx.com/v2/dynamic_emergency_endpoints

Dynamic Emergency Endpoints are used to create additional information regarding the origin of an e911 call. An endpoint can be associated with office booths, rooms, building floors, etc.

Common DLR use cases have a single Emergency Address and Multiple Emergency Endpoints.

Step 1: Create a new Dynamic Emergency Address

First, we need to create a Dynamic Emergency Address to be associated with an endpoint.

curl -L -X POST 'https://api.telnyx.com/v2/dynamic_emergency_addresses' -H 'Authorization: Bearer YOUR API KEY' -H 'Content-Type: application/json' --data-raw '{
 "house_number": "1901",
 "street_pre_directional": "W",
 "street_name": "MADISON",
 "street_suffix": "ST",
 "extended_address": "West Madison Street ",
 "locality": "CHICAGO",
 "administrative_area": "IL",
 "postal_code": "60612",
 "country_code": "US"
}'
{
   "data": {
       "street_pre_directional": "W",
       "house_number": "1901",
       "postal_code": "60612",
       "created_at": "2021-09-21T23:21:20.607173Z",
       "extended_address": "WEST MADISON STREET",
       "updated_at": "2021-09-21T23:21:20.607174Z",
       "administrative_area": "IL",
       "street_post_directional": null,
       "street_name": "MADISON",
       "house_suffix": null,
       "locality": "CHICAGO",
       "status": "pending",
       "id": "f7a13541-ca9e-45c5-8268-e928396471df",
       "sip_geolocation_id": "d4f52baed311ef95",
       "country_code": "US",
       "street_suffix": "ST",
       "record_type": "dynamic_emergency_address"
   }
}

In response to our request we will get a summary of the newly created Dynamic Emergency Address.

Please note the status parameter is pending. This is due to asynchronous validation over the address details.

Step 2: Query for Dynamic Emergency Address

To check if Dynamic Emergency Address was correctly validated we can query for the created Address using the id parameter.

curl -L -X GET 'https://api.telnyx.com/v2/dynamic_emergency_addresses/f7a13541-ca9e-45c5-8268-e928396471df' -H 'Authorization: Bearer YOUR API KEY'
{
   "data": {
       "status": "activated",
       "street_post_directional": "",
       "street_pre_directional": "W",
       "postal_code": "60612",
       "locality": "CHICAGO",
       "extended_address": "WEST MADISON STREET",
       "street_name": "MADISON",
       "administrative_area": "IL",
       "country_code": "US",
       "house_suffix": "",
       "street_suffix": "ST",
       "created_at": "2021-09-21T23:21:20.607173Z",
       "sip_geolocation_id": "d4f52baed311ef95",
       "updated_at": "2021-09-21T23:21:23.657740Z",
       "house_number": "1901",
       "id": "f7a13541-ca9e-45c5-8268-e928396471df",
       "record_type": "dynamic_emergency_address"
   }
}
  • In the above response, status activated means the address was correctly validated.
  • The sip_geolcation_id parameter is the geolocation id that uniquely identifies this Emergency Dynamic Address.
  • Users can configure multiple Emergency Dynamic Addresses and each one will have a unique sip_geolocation_id value.
  • The id parameter represents the Dynamic Emergency Address ID that will be used to associate a Dynamic Emergency Address to a Dynamic Emergency Endpoint.

Geolocation id "d4f52baed311ef95" is one of the parameter values that needs to be added to the SIP INVITE when a call to 911 is performed (refer to Part 2: Call Handling using Dynamic Endpoints, below).

Step 3: Create a new Dynamic Emergency Endpoint and associate Dynamic Emergency Address ID

Now we create a Dynamic Emergency Endpoint that will be associated with the newly created Dynamic Emergency Address. This association will be done using the Emergency Address id parameter.

curl -L -X POST 'https://api.telnyx.com/v2/dynamic_emergency_endpoints' -H 'Authorization: Bearer YOUR API KEY' -H 'Content-Type: application/json' --data-raw '{
"callback_number":"+13125550000",
"caller_name":"Jane Doe",
"dynamic_emergency_address_id":"f7a13541-ca9e-45c5-8268-e928396471df"
}
{
   "data": {
       "status": "activated",
       "sip_from_id": "2d117a0a1dee74f1",
       "caller_name": "Jane Doe",
       "callback_number": "+13125550000",
       "created_at": "2021-09-21T23:33:12.334938Z",
       "updated_at": "2021-09-21T23:33:12.334942Z",
       "id": "64798021-5f31-46e0-965b-60196fd46cfe",
       "Dynamic_emergency_address_id": "f7a13541-ca9e-45c5-8268-e928396471df",
       "record_type": "dynamic_emergency_endpoint"
   }
}

In response to our request we will get a summary of the newly created Dynamic Emergency Address Endpoint and a new parameter sip_from_id is returned.

Parameter sip_from_id value "2d117a0a1dee74f1" is another parameter value that needs to be added to the SIP INVITE when a call to 911 is performed (refer to Part 2: Call Handling using Dynamic Endpoints, below).

After completing the configuration steps we get two important parameter values that will be used together on SIP INVITES for calling 911 using Dynamic Routing: 1. sip_geolocation_id: 4f52baed311ef95 from Dynamic Emergency Address 2. sip_from_id: 2d117a0a1dee74f1 from Dynamic Emergency Ednpoints


Part 2: Call Handling using Dynamic Endpoints

Once Dynamic Emergency Address and Dynamic Emergency endpoints are properly configured, we can leverage them to enrich information to be sent to 911 service.

Call Handling implementation should be defined by each customer.

When making a call to 911 service, SIP INVITE needs to be sent in the following way:

The sip_from_id parameter value 2d117a0a1dee74f1 needs to be added to the From SIP header to identify the Dynamic Endpoint, and the sip_geolocation_id parameter value d4f52baed311ef95 needs to be added to a new SIP header Geolocation

SIP INVITE:

INVITE sip:[email protected] SIP Proxy:5060 SIP/2.0
Via: SIP/2.0/UDP Telnyx Media IP:5060;branch=z9hG4bK-4126-1-0
From: sipp <sip:[email protected] Media IP:5060>;tag=4126SIPpTag001
To: 933 <sip:[email protected] SIP Proxy:5060>
Call-ID: [email protected] Media IP
CSeq: 1 INVITE
Contact: sip:[email protected] Media IP:5060
Max-Forwards: 70
Subject: Performance Test
Geolocation:d4f52baed311ef95
Content-Type: application/sdp
Content-Length:   135

v=0
o=user1 53655765 2353687637 IN IP4 Telnyx Media IP
s=-
c=IN IP4 Telnyx Media IP
t=0 0
m=audio 6036 RTP/AVP 0
a=rtpmap:0 PCMU/8000

Alternatively, the sip_from_id parameter value 2d117a0a1dee74f1 can also be added to the P-Asserted-Identity SIP header, in addition to the From header:

Via: SIP/2.0/UDP Telnyx Media IP:5060;branch=z9hG4bK-4126-1-0
From: sipp <sip:[email protected] Media IP:5060>;tag=4126SIPpTag001
To: 933 <sip:[email protected] SIP Proxy:5060>
Call-ID: [email protected] Media IP
CSeq: 1 INVITE
Contact: sip:[email protected] Media IP:5060
Max-Forwards: 70
P-Asserted-Identity: <sip:[email protected]:5060>
Subject: Performance Test
Geolocation:d4f52baed311ef95
Content-Type: application/sdp
Content-Length:   135

v=0
o=user1 53655765 2353687637 IN IP4 Telnyx Media IP
s=-
c=IN IP4 Telnyx Media IP
t=0 0
m=audio 6036 RTP/AVP 0
a=rtpmap:0 PCMU/8000

With the Dynamic Emergency parameters sent on the call above, Telnyx will fetch the information associated with Dynamic Emergency Address and Emergency Dynamic Endpoint created and relay that information to e911 services.

The information e911 will see is the following:

"street_pre_directional": "W",
"postal_code": "60612",
"locality": "CHICAGO",
"extended_address": "WEST MADISON STREET",
"street_name": "MADISON",
"administrative_area": "IL",
"country_code": "US",
"street_suffix": "ST",
"house_number": "1901",
"caller_name": "Jane Doe",
"callback_number": "+13125550000",

Emergency Address Character Limits

The table below depicts the maximum number of characters allowed in each field of Dynamic Emergency Address endpoint, as well as our recommendation of character limits under the Recommended Character Limit column.

Field NameRequiredCharacter LimitRecommended Character LimitPIDF-LO
Number PrefixNo6n/aHNO
Number SuffixNo454HNS
Pre DirectionalNo22PRD
Street NameYes200100RD
Street SuffixNo4510STS
Post DirectionalNo22POD
Address Line 2No60; Our system will automatically abbreviate some common terms like APARTMENT or FLOOR*20LOC
CityYes100100A3
State/ProvinceYes2; Must be a valid USPS state code or Canada Post province code2A1
Zip/Postal CodeYes10; Must be a valid USPS zip code or Canada postal code10PC
Plus 4No104
CountryYes2; Currently only the US (United States) and CA (Canada) are supported2country
Caller NameNo5032

*Address Line 2 Abbreviations

Here are some example Address Line 2 inputs and corresponding abbreviated outputs:

Input Unit TypeAbbreviated Unit Type
APARTMENTAPT
BASEMENTBSMT
BUILDINGBLDG
DEPARTMENTDEPT
FLOORFL
FRONTFRNT
HANGARHNGR
LOBBYLBBY
LOTLOT
LOWERLOWR
OFFICEOFC
PENTHOUSEPH
PIERPIER
REARREAR
ROOMRM
SIDESIDE
SLIPSLIP
SPACESPC
STOPSTOP
SUITESTE
TRAILERTRLR
UNITUNIT
UPPERUPPR
Was this page helpful?