Rewrite the E911 platform guide to use new native, self-service REST endpoint

fern/products/platform/pages/platform/phone-numbers/e911.mdx

@@ -2,53 +2,91 @@
 id: 5286e8ea-58ec-472a-8645-ade919b8449b
 title: E911
 slug: /e911
-x-custom:
-  ported_from_readme: true
+description: Register an emergency address and enable E911 service for your SignalWire phone numbers.
+max-toc-depth: 3
 ---
 
-### What is E911?
+**E911, or Enhanced 911,** is a support system for wireless and VoIP phone users who dial 911,
+the standard number for requesting help in an emergency across supported countries.
+Because a VoIP number isn't tied to a physical line, you register a street address for the number ahead of time.
+When someone dials 911 from that number, the call is routed to the dispatch center serving the registered
+address, and that address is displayed to the dispatcher.
 
-**E911, or Enhanced 911,** is a support system for wireless and VoIP phone users who dial 911, the standard number for requesting help in an emergency across supported countries. 
-Since wireless users are often mobile, this enhancement helps the 911 service by allowing the location of the user to be reported to the call receiver.
+E911 on SignalWire is self-service: create an emergency address, assign it to a phone number,
+and the number is provisioned for emergency calling. You can manage everything from the
+[Dashboard](#set-up-e911-in-the-dashboard) or the [REST API](#set-up-e911-with-the-rest-api).
 
-**SignalWire Addresses** allows for a collection of addresses in your SignalWire Space so that they can be utilized for uses like E911 or phone number locality requirements for certain countries around the world.
+## How it works
 
-<Warning title="E911 requires a support request">
-By default, SignalWire phone numbers purchased through the Dashboard don’t support E911.
-To enable E911 services, contact the SignalWire Support Team by creating a support ticket in your Dashboard.
-</Warning>
+Emergency addresses live in your Space as a reusable collection, so one address can serve many phone numbers.
+When you create an address with emergency service enabled, it is validated against the carrier's emergency
+database, and small errors are corrected automatically.
 
-### Testing E911
+Assigning a validated address to a phone number starts provisioning at the carrier.
+Provisioning is asynchronous: the number's E911 status starts as `pending` and becomes `active`
+once the carrier confirms. The address's label is presented to the dispatcher as the caller name,
+so use a label that identifies the caller or location clearly.
 
-There is a proper way to test E911 for your SignalWire number. 
-It's best to arrange a test call to 911 services and verify the E911 information pops up on their screen correctly. 
-You can call your local 911 center non-emergency number, and notify them you're testing a VOIP system for the correct display of location information. 
+## Set up E911 with the REST API
+
+First, create an address with `emergency_enabled` set to `true`:
+
+<EndpointRequestSnippet endpoint="POST /api/relay/rest/addresses" />
+
+If the carrier can't validate the address, the request fails with a `422` response listing the
+problems and, when available, suggested corrections in a `candidates` array.
+
+Next, assign the address to a phone number:
+
+<EndpointRequestSnippet endpoint="POST /api/relay/rest/phone_numbers/{id}/e911_address" />
+
+The phone number's `e911_status` field tracks provisioning; the number is ready for emergency
+calling once it reads `active`. To disable E911 on the number, send a `DELETE` request to the
+same endpoint.
+
+For all operations and full request and response details, see the
+[E911 Addresses](/docs/apis/rest/e-911-addresses/list-addresses) reference.
+
+<Info title="Compatibility API">
+If you manage numbers with the Compatibility API, you can attach an existing emergency address by
+setting `EmergencyAddressSid` when
+[updating an incoming phone number](/docs/compatibility-api/rest/incoming-phone-numbers/update-incoming-phone-number).
+</Info>
+
+## Set up E911 in the Dashboard
+
+Open the **Phone Numbers** section of your Dashboard and select the **E911** tab to create and
+manage emergency addresses. To assign an address, open a phone number's detail page and set its
+emergency address there. The same validation and provisioning process applies, and the number's
+E911 status is shown alongside the assignment.
+
+## Test your E911 configuration
+
+There is a proper way to test E911 for your SignalWire number.
+It's best to arrange a test call to 911 services and verify the E911 information pops up on their screen correctly.
+You can call your local 911 center non-emergency number, and notify them you're testing a VoIP system for the correct display of location information.
 You should be able to get the non-emergency phone number from local law enforcement or an internet search. All 911 centers have a non-emergency number for testing purposes.
 
 <Info>
 
 ["How do I place a "test" call to make sure 911 works for me?"](https://www.911.gov/frequently_asked_questions.html)
 
-"Test calls confirm that your local 911 service can receive your 911 call and has the correct location information. 
-Test calls can be scheduled by contacting your local 911 call center via its non-emergency phone number. 
-To contact the local 911 center responsible for answering calls from your location, go 
-[here](https://www.nasna911.org/contact-911) and click on the state in which you are located. 
+"Test calls confirm that your local 911 service can receive your 911 call and has the correct location information.
+Test calls can be scheduled by contacting your local 911 call center via its non-emergency phone number.
+To contact the local 911 center responsible for answering calls from your location, go
+[here](https://www.nasna911.org/contact-911) and click on the state in which you are located.
 The person responsible for operating the state’s 911 system will be identified, and they should know who you should talk to at your local 911 call center, to schedule a day and time for test calls."
 
 </Info>
 
-As stated before, SignalWire phone numbers purchased through the Dashboard don’t support E911. 
-If you'd like to have E911 services enabled, please contact the SignalWire Support Team. 
-Once E911 is enabled for the number by working with the SignalWire support team, you can follow these steps to set up E911 and make a test call:
+Once you've assigned an emergency address to your number, follow these steps to verify it:
 
-1. Complete the Set of Instructions from the Previous Section.
-2. Wait about 30 minutes for SignalWire to properly set up E911 on your line.
-3. Do a test call to 933 first, and listen to your E911 info playback. 
-_If you hear the automated information, you're ready to do a real test. 
+1. Wait for the number's E911 status to become `active`.
+2. Do a test call to 933 first, and listen to your E911 info playback.
+_If you hear the automated information, you're ready to do a real test.
 If you hear an error tone, wait a little longer, then try again._
-4. Call your local police department's non-emergency number. 
+3. Call your local police department's non-emergency number.
 Let them know you're making a VoIP test call to verify location information.
-5. Once you've notified your local emergency center of an incoming test call, make the real call to 911 and verify your address displays correctly with the answering personnel.
+4. Once you've notified your local emergency center of an incoming test call, make the real call to 911 and verify your address displays correctly with the answering personnel.
 
-Provided all the information displays correctly, your verification process for E911 services is complete. 
-The carriers validate the address. If it passes, you're good to go.
+Provided all the information displays correctly, your verification process for E911 services is complete.

fern/products/platform/pages/platform/phone-numbers/overview.mdx

@@ -87,4 +87,4 @@ You can delete a number group from its settings page. Deleting the group will ca
 
 ## E911
 
-Manage addresses for emergency services in the **E911** tab. See [What is E911?](/docs/platform/e911) for setup and testing instructions.
+Create and manage emergency addresses in the **E911** tab, then assign one to a number from its detail page. See the [E911 guide](/docs/platform/e911) for setup and testing instructions, or use the [REST API](/docs/apis/rest/e-911-addresses/list-addresses) to manage E911 programmatically.