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.

Telnyx supports two methods for providing location information during emergency calls:

1. API-based address provisioning - Pre-configure emergency addresses and endpoints using Telnyx APIs (recommended for fixed locations).
2. Built-in geolocation - Pass latitude/longitude coordinates directly in SIP headers (ideal for mobile devices, wearables, and IoT).

In this guide you'll learn how to set up Dynamic Location Routing for emergency calling using both methods.

Before using either emergency calling method, you must enable emergency services for your phone numbers in the Telnyx Portal:

1. Navigate to Numbers > Manage Numbers in the Telnyx Portal.
2. Select the phone number you want to configure.
3. Click the Emergency tab.
4. Enable emergency calling for the number.

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 an E911 call may originate from. This address is normally associated with office locations, business locations, etc.

2. 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.

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.

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_geolocation_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 Call Handling using Dynamic Endpoints, below).

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

Telnyx's built-in geolocation feature enables precise emergency calling for devices with GPS capabilities by allowing you to pass latitude and longitude coordinates directly in SIP headers. This method is ideal for:

• Wearables - Smartwatches and fitness devices with GPS.
• Telematics - Connected vehicles and fleet management systems.
• IoT devices - Asset trackers and mobile sensors.
• Mobile applications - Apps running on smartphones or tablets.

Unlike the API-based method which requires pre-provisioning fixed addresses, the coordinate-based method allows dynamic location updates in real-time, making it perfect for mobile and constantly moving devices.

With built-in geolocation, your application passes the device's current GPS coordinates (latitude and longitude) directly in the SIP INVITE headers when placing a 911 or 933 emergency call. Telnyx automatically converts these coordinates into a PIDF-LO (Presence Information Data Format-Location Object) and routes the call to the appropriate Public Safety Answering Point (PSAP) with accurate location information.

Your application must obtain the current GPS coordinates from the device. The coordinates must be in decimal degrees format:

• Latitude: Range from -90 to +90 (negative for South, positive for North).
• Longitude: Range from -180 to +180 (negative for West, positive for East).
• Precision: Recommended 6-8 decimal places for meter-level accuracy.

Example coordinates (Chicago, IL):

Latitude:  41.8781   # North (positive value)
Longitude: -87.6298  # West (negative value)

Create a PIDF-LO XML document containing the GPS coordinates following RFC 4119 and RFC 5491 standards:

<?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:gml="http://www.opengis.net/gml"
          xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
          entity="sip:user@example.com">
  <dm:device id="device1">
    <gp:geopriv>
      <gp:location-info>
        <gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
          <gml:pos>41.8781 -87.6298</gml:pos>
        </gml:Point>
      </gp:location-info>
      <gp:usage-rules>
        <gp:retransmission-allowed>false</gp:retransmission-allowed>
      </gp:usage-rules>
    </gp:geopriv>
    <dm:timestamp>2024-01-15T10:30:00Z</dm:timestamp>
  </dm:device>
</presence>

important

• Coordinates in <gml:pos> must be specified as latitude longitude (space-separated)
• The example above uses the same Chicago coordinates from Step 1: 41.8781 -87.6298
• The srsName attribute must be urn:ogc:def:crs:EPSG::4326 (WGS84 coordinate system)
• Include a timestamp in ISO 8601 format

Add the PIDF-LO XML as a multipart body in your SIP INVITE message when calling 911 or 933. The Geolocation header should reference the PIDF-LO content:

INVITE sip:911@sip.telnyx.com SIP/2.0
Via: SIP/2.0/UDP 192.0.2.10:5060;branch=z9hG4bK-1234-1-0
From: <sip:+13125550100@sip.telnyx.com>;tag=1234SIPpTag001
To: 911 <sip:911@sip.telnyx.com>
Call-ID: emergency-call-001@192.0.2.10
CSeq: 1 INVITE
Contact: <sip:+13125550100@192.0.2.10:5060>
Max-Forwards: 70
Geolocation: <cid:location@example.com>
Content-Type: multipart/mixed;boundary=boundary1

--boundary1
Content-Type: application/sdp

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

--boundary1
Content-Type: application/pidf+xml
Content-ID: <location@example.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:gml="http://www.opengis.net/gml"
          xmlns:dm="urn:ietf:params:xml:ns:pidf:data-model"
          entity="sip:+13125550100@sip.telnyx.com">
  <dm:device id="wearable-device-001">
    <gp:geopriv>
      <gp:location-info>
        <gml:Point srsName="urn:ogc:def:crs:EPSG::4326">
          <gml:pos>41.8781 -87.6298</gml:pos>
        </gml:Point>
      </gp:location-info>
      <gp:usage-rules>
        <gp:retransmission-allowed>false</gp:retransmission-allowed>
      </gp:usage-rules>
    </gp:geopriv>
    <dm:timestamp>2024-01-15T10:30:00Z</dm:timestamp>
  </dm:device>
</presence>

--boundary1--

note

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

• Use at least 6 decimal places for coordinates (provides ~0.1 meter accuracy).
• Verify GPS signal quality before obtaining coordinates.
• Include altitude if available for multi-story buildings.

• Obtain fresh GPS coordinates immediately before placing emergency call.
• Include accurate timestamp in PIDF-LO.
• Update coordinates if call is retried.

• Implement fallback to last-known-good location if GPS is unavailable.
• Consider caching recent coordinates for areas with poor GPS signal.
• Provide user notification if location accuracy is degraded.

• Test emergency calling in your development environment using test numbers (933).
• Verify PIDF-LO XML validates against RFC 4119 schema.
• Confirm coordinates are correctly formatted (latitude first, then longitude).

warning

Never test emergency calling using real 911 numbers. Use Telnyx test number 933 for development and testing purposes. The 933 test number simulates an emergency call without dispatching actual emergency services, allowing you to verify your location data and call routing configuration safely.

Feature	Built-in geolocation (coordinate-based)	API-based addresses
Best for	Mobile devices, wearables, IoT	Fixed locations, office phones
Setup	Pass coordinates in SIP	Pre-provision via API
Location updates	Real-time with each call	Requires API update
Precision	GPS-level accuracy	Street address accuracy
Use cases	Vehicle tracking, smartwatches	Office buildings, residential
Configuration	No API calls needed	API setup required

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

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