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:

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.

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"
}'

Note
After pasting the above content, Kindly check and remove any new line added

{
   "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"
   }
}

Note
After pasting the above content, Kindly check and remove any new line added

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'

Note
After pasting the above content, Kindly check and remove any new line added

{
   "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"
   }
}

Note
After pasting the above content, Kindly check and remove any new line added

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"
}

Note
After pasting the above content, Kindly check and remove any new line added

{
   "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"
   }
}

Note
After pasting the above content, Kindly check and remove any new line added

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:

sip_geolocation_id: 4f52baed311ef95 from Dynamic Emergency Address
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:933@Telnyx SIP Proxy:5060 SIP/2.0
Via: SIP/2.0/UDP Telnyx Media IP:5060;branch=z9hG4bK-4126-1-0
From: sipp <sip:2d117a0a1dee74f1@Telnyx Media IP:5060>;tag=4126SIPpTag001
To: 933 <sip:1818933@Telnyx SIP Proxy:5060>
Call-ID: 1-4126@Telnyx Media IP
CSeq: 1 INVITE
Contact: sip:sipp@Telnyx 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

Note
After pasting the above content, Kindly check and remove any new line added

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:

INVITE sip:933@Telnyx SIP Proxy:5060 SIP/2.0
Via: SIP/2.0/UDP Telnyx Media IP:5060;branch=z9hG4bK-4126-1-0
From: sipp <sip:2d117a0a1dee74f1@Telnyx Media IP:5060>;tag=4126SIPpTag001
To: 933 <sip:1818933@Telnyx SIP Proxy:5060>
Call-ID: 1-4126@Telnyx Media IP
CSeq: 1 INVITE
Contact: sip:sipp@Telnyx Media IP:5060
Max-Forwards: 70
P-Asserted-Identity: <sip:2d117a0a1dee74f1@sbc.example.com: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

Note
After pasting the above content, Kindly check and remove any new line added

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",

Note
After pasting the above content, Kindly check and remove any new line added

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 Name	Required	Character Limit	Recommended Character Limit	PIDF-LO
Number Prefix	No	6	n/a	HNO
Number Suffix	No	45	4	HNS
Pre Directional	No	2	2	PRD
Street Name	Yes	200	100	RD
Street Suffix	No	45	10	STS
Post Directional	No	2	2	POD
Address Line 2	No	60; Our system will automatically abbreviate some common terms like APARTMENT or FLOOR	20	LOC
City	Yes	100	100	A3
State/Province	Yes	2; Must be a valid USPS state code or Canada Post province code	2	A1
Zip/Postal Code	Yes	10; Must be a valid USPS zip code or Canada postal code	10	PC
Plus 4	No	10	4
Country	Yes	2; Currently only the US (United States) and CA (Canada) are supported	2	country
Caller Name	No	50	32

*Address Line 2 Abbreviations

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

Input Unit Type	Abbreviated Unit Type
APARTMENT	APT
BASEMENT	BSMT
BUILDING	BLDG
DEPARTMENT	DEPT
FLOOR	FL
FRONT	FRNT
HANGAR	HNGR
LOBBY	LBBY
LOT	LOT
LOWER	LOWR
OFFICE	OFC
PENTHOUSE	PH
PIER	PIER
REAR	REAR
ROOM	RM
SIDE	SIDE
SLIP	SLIP
SPACE	SPC
STOP	STOP
SUITE	STE
TRAILER	TRLR
UNIT	UNIT
UPPER	UPPR

Emergency Calling - Dynamic e911

Part 1: Configuration using Emergency API

Step 1: Create a new Dynamic Emergency Address ​

Step 2: Query for Dynamic Emergency Address ​

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

Part 2: Call Handling using Dynamic Endpoints

Emergency Address Character Limits

*Address Line 2 Abbreviations ​

Step 1: Create a new Dynamic Emergency Address

Step 2: Query for Dynamic Emergency Address

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

*Address Line 2 Abbreviations