Emergency Resources#

Use Emergency Resources to register DID phone numbers for emergency calling services, including E911 and E112, through the DIDWW API.

Emergency calling requirements depend on the country and DID Group Type. Customers must provide valid Identity and Address information for the emergency location before routing can be activated. This emergency workflow is separate from the end-user registration workflow described in Regulation Resources.

Start with the endpoint that matches your current task:

To find eligible numbers, retrieve DIDs and select active DIDs whose DID Groups support the emergency feature.
To discover the applicable rules and pricing, retrieve Emergency Requirements.
To check an Identity and Address before submission, create an Emergency Requirement Validation.
To register DIDs or submit a replacement address, create an Emergency Verification.
To monitor a submission, retrieve the Emergency Verification or configure a callback when creating it.
To inspect or cancel the resulting service, retrieve an Emergency Calling Service or delete the Emergency Calling Service.

Resource overview#

Resource	Use it to
Emergency Requirements	Determine the Identity type, geographic scope, mandatory fields, estimated setup time, restrictions, and pricing for a country and DID Group Type.
Emergency Requirement Validations	Check whether an Identity and Address satisfy an Emergency Requirement before creating an Emergency Verification.
Identities	Create or reuse the personal or business Identity required for the emergency registration.
Addresses	Create or reuse the emergency location linked to the selected Identity.
Emergency Verifications	Submit a new service or address update for review, monitor its status, and inspect rejection details.
Emergency Calling Services	Retrieve the service created by a verification, monitor activation and renewal, or cancel the service.
DIDs	Find emergency-capable numbers and manage their Emergency Calling Service assignments.

Common workflow#

A typical emergency calling workflow starts by selecting compatible DIDs and finding the single Emergency Requirement that applies to their country and DID Group Type.

Eligible DID or DIDs
 └─ Emergency Requirement (Country + DID Group Type)
    ├─ Identity
    ├─ Address
    ├─ Emergency Requirement Validation
    └─ Emergency Verification
       ├─ New Calling Service → Emergency Calling Service
       └─ Existing Calling Service → replacement address review
          └─ pending → approved or rejected

Note

For complete examples, see Register Emergency Calling Service and Update Emergency Calling Service.

1. Select compatible DIDs#

Use Retrieve All DIDs with filter[did_group.features]=emergency to find DIDs whose DID Groups support emergency calling. You can also use filter[emergency_enabled]=false to find DIDs where emergency routing is not active.

Before continuing, confirm that:

Every selected DID is active and supports the emergency feature.
The selected DIDs have the same country and DID Group Type.
The emergency_calling_service relationship is empty for each DID that will be used to create a new service.

Important

emergency_enabled=false does not guarantee that a DID is available for a new Emergency Calling Service. Always inspect its emergency_calling_service relationship. A DID already assigned to another Emergency Calling Service cannot be submitted for a new service.

If a DID already has an approved end-user registration, the emergency registration must use an Address linked to the same Identity. Include the identity and address_verification relationships when retrieving DIDs so that this condition can be identified before submission.

2. Identify the applicable requirement#

Use Retrieve All Emergency Requirements and filter the results by the selected DIDs’ country.id and did_group_type.id. Inspect the returned requirement before creating or selecting the Identity and Address, especially:

identity_type and the personal or business area level.
address_area_level and any required geographic scope.
personal_mandatory_fields, business_mandatory_fields, and address_mandatory_fields.
estimate_setup_time and requirement_restriction_message.
meta.setup_price and meta.monthly_price.

Access to Emergency Resources requires an emergency calling plan. Requests return 403 Forbidden when the account does not have one assigned. When a matching plan rate exists, meta.monthly_price shows the recurring price and meta.setup_price is 0.0 because an emergency service setup fee is not charged through the API. A null price means that no matching rate was found.

3. Create or reuse the Identity and Address#

Emergency Requirements support personal and business Identities. Use Retrieve All Identities and Retrieve All Addresses to find records that satisfy the applicable requirement. If suitable records do not exist, create an Identity and then create an Address linked to that Identity and the required country.

Supply every field listed in the requirement’s mandatory field arrays. If the DID already has approved end-user registration, reuse that registration’s Identity and select or create an Address linked to it.

4. Validate the prepared records#

Create an Emergency Requirement Validation with the Emergency Requirement, Identity, and Address IDs. A 201 Created response confirms that the records satisfy the selected requirement. A 422 Unprocessable Entity response identifies missing or invalid information that should be corrected before the verification is submitted.

5. Create a new Emergency Calling Service#

Create an Emergency Verification in New Calling Service mode. Provide the validated address relationship and at least one DID in the dids relationship. Do not provide an emergency_calling_service relationship in this mode.

The Emergency Calling Service is created automatically from this verification. It cannot be created directly. All Emergency Verifications are reviewed by the DIDWW Emergency Team. When the verification is approved and the service status becomes active, emergency routing is enabled for the associated DIDs.

Important

Do not create an Order to purchase emergency calling. When the Emergency Calling Service is activated, DIDWW creates the related Order automatically. If an Order callback is configured, that activation also triggers it.

6. Monitor the verification and service#

Use Retrieve Emergency Verification to inspect status, reject_reasons, and reject_comment. Use Retrieve Emergency Calling Service to confirm that the associated service becomes active.

You can set callback_url and callback_method when creating a verification to receive an approved or rejected notification. When callback_url is supplied, callback_method must be get or post. See Callbacks Details for the payload and signature-validation guidance.

If the verification is rejected, review its rejection details, correct the data, and create another Emergency Verification in Existing Calling Service mode for the service whose status is changes_required.

7. Update an existing service address#

First, retrieve the Emergency Calling Service and confirm that its status is new, changes_required, or active. Address updates are rejected with 422 Unprocessable Entity when the service is in_process, pending_update, or canceled.

Prepare and validate the replacement Address against the service’s Emergency Requirement. Then create an Emergency Verification in Existing Calling Service mode with the new address and existing emergency_calling_service relationships. Do not provide the dids relationship in this mode.

For an active service, its status becomes pending_update while the replacement address is reviewed. Emergency routing remains enabled with the current address during the review. The new address takes effect only after approval, when the service returns to active. If the update is rejected, inspect reject_reasons and reject_comment, correct the data, and submit another verification.

8. Manage assigned DIDs or cancel the service#

Add or remove DIDs through Update DID rather than by creating an address-update verification. Unassigning a DID does not immediately cancel its Emergency Calling Service. A service with no remaining DIDs is automatically canceled within a few hours, and DIDWW notifies the customer.

To cancel the entire service explicitly, use Delete Emergency Calling Service. A service can be canceled when its status is new, changes_required, active, or pending_update.

Requirement scope#

Emergency Requirements can restrict where the Identity and Address must be located and can make otherwise optional fields mandatory.

Identity location#

The personal_area_level and business_area_level attributes support:

Value	Meaning
`world_wide`	An Identity from any country can be used.
`country`	The Identity must be from the requirement country.

Address location#

The address_area_level attribute supports:

Value	Meaning
`country`	The Address must be within the requirement country.
`area`	The Address must be within the locality or region covered by the DID prefix.
`city`	The Address must be from the same city as the registered DIDs.

Mandatory fields#

The personal_mandatory_fields and business_mandatory_fields arrays may contain:

Attribute	Meaning
`birth_date`	Birth date of a person.
`personal_tax_id`	Personal tax number.
`id_number`	Proof of ID number.
`vat_id`	VAT or tax number.
`company_reg_number`	Company registration number.
`contact_email`	Contact email address.
`country`	Country of tax residence.
`company_representative_date_of_birth`	Company representative’s date of birth.

The address_mandatory_fields array may contain area, which represents the state, province, or region.

Status values#

Emergency Verification statuses#

Status	Meaning
`pending`	The verification has been submitted and is awaiting a decision.
`approved`	The submitted emergency information has been approved.
`rejected`	The submission was rejected. Inspect `reject_reasons` and `reject_comment`.

Emergency Calling Service statuses#

Status	Meaning
`new`	The service has been created but is not yet active.
`in_process`	The service verification is under review by the DIDWW Emergency Team.
`changes_required`	The verification was rejected and a corrected verification must be submitted.
`pending_update`	An update to an active service is under review.
`active`	The service is approved and emergency calling is operational.
`canceled`	The service has been permanently canceled.