# 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](../regulation-resources/index.html).

Start with the endpoint that matches your current task:

- To find eligible numbers, [retrieve DIDs](../inventory-resources/did/get-dids.html) and
  select active DIDs whose DID Groups support the `emergency` feature.
- To discover the applicable rules and pricing, [retrieve Emergency Requirements](emergency-requirements/get-emergency-requirements.html).
- To check an Identity and Address before submission, create an
  [Emergency Requirement Validation](emergency-requirements/emergency-requirement-validations.html).
- To register DIDs or submit a replacement address, [create an Emergency Verification](emergency-verifications/create-emergency-verification.html).
- To monitor a submission, [retrieve the Emergency Verification](emergency-verifications/get-emergency-verification.html) or configure a callback when
  creating it.
- To inspect or cancel the resulting service, [retrieve an Emergency Calling Service](emergency-calling-services/get-emergency-calling-service.html) or [delete the Emergency
  Calling Service](emergency-calling-services/delete-emergency-calling-service.html).

## Resource overview

| Resource | Use it to |
| --- | --- |
| [Emergency Requirements](emergency-requirements/index.html) | Determine the Identity type, geographic scope, mandatory fields, estimated setup time, restrictions, and pricing for a country and DID Group Type. |
| [Emergency Requirement Validations](emergency-requirements/emergency-requirement-validations.html) | Check whether an Identity and Address satisfy an Emergency Requirement before creating an Emergency Verification. |
| [Identities](../regulation-resources/identities/index.html) | Create or reuse the personal or business Identity required for the emergency registration. |
| [Addresses](../regulation-resources/addresses/index.html) | Create or reuse the emergency location linked to the selected Identity. |
| [Emergency Verifications](emergency-verifications/index.html) | Submit a new service or address update for review, monitor its status, and inspect rejection details. |
| [Emergency Calling Services](emergency-calling-services/index.html) | Retrieve the service created by a verification, monitor activation and renewal, or cancel the service. |
| [DIDs](../inventory-resources/did/index.html) | 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](../../examples/register-emergency-calling-service.html)
and [Update Emergency Calling
Service](../../examples/update-emergency-calling-service.html).

### 1. Select compatible DIDs

Use [Retrieve All DIDs](../inventory-resources/did/get-dids.html) 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](emergency-requirements/get-emergency-requirements.html) 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](../regulation-resources/identities/get-identities.html) and [Retrieve All
Addresses](../regulation-resources/addresses/get-addresses.html) to find records that satisfy
the applicable requirement. If suitable records do not exist, [create an
Identity](../regulation-resources/identities/create-identity.html) and then [create an
Address](../regulation-resources/addresses/create-address.html) 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](emergency-requirements/emergency-requirement-validations.html) 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](emergency-verifications/create-emergency-verification.html) 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](emergency-verifications/get-emergency-verification.html) to inspect `status`,
`reject_reasons`, and `reject_comment`. Use [Retrieve Emergency Calling
Service](emergency-calling-services/get-emergency-calling-service.html) 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](../callbacks-details.html) 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](emergency-calling-services/get-emergency-calling-service.html) 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](emergency-verifications/create-emergency-verification.html) 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](../inventory-resources/did/update-did.html) 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](emergency-calling-services/delete-emergency-calling-service.html). 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. |

## Related resources

- [Regulation Resources](../regulation-resources/index.html) - Create and manage the
  Identities and Addresses reused by emergency registration.
- [Coverage Resources](../coverage-resources/index.html) - Find DID Groups that support
  emergency calling and identify their country and DID Group Type.
- [DIDs](../inventory-resources/did/index.html) - Find eligible phone numbers and manage
  their Emergency Calling Service assignments.
- [Outbound Trunks](../inventory-resources/voice-out-trunks/index.html) - Configure
  outbound routing after the Emergency Calling Service becomes active.
- [Orders](../inventory-resources/order/index.html) - Retrieve the Order that DIDWW creates
  automatically when the Emergency Calling Service is activated.
- [Callbacks Details](../callbacks-details.html) - Handle Emergency Verification and
  related Order status notifications.

On this page