# Emergency Calling Services

Use the Emergency Calling Services resource to retrieve and cancel emergency calling
services associated with DID phone numbers in the account.

An Emergency Calling Service represents an emergency calling subscription and its assigned
DIDs. It provides the service name, reference, status, activation and renewal details,
pricing, and relationships to its country, DID Group Type, Order, Emergency Requirement,
latest Emergency Verification, and DIDs.

Emergency Calling Services cannot be created directly. A service is created automatically
when an [Emergency Verification](../emergency-verifications/index.html) is submitted in
**New Calling Service** mode. Use **Existing Calling Service** mode to submit a replacement
address for an existing service.

Note

For the complete registration and service-management workflow, see [Emergency
Resources](../index.html). 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).

Choose the operation that matches your task:

- To find and monitor services, [retrieve all Emergency Calling Services](get-emergency-calling-services.html).
- To inspect one service and its related records, [retrieve an Emergency Calling
  Service](get-emergency-calling-service.html).
- To change a registered address, [create an Emergency Verification](../emergency-verifications/create-emergency-verification.html) in **Existing Calling
  Service** mode.
- To add or remove an assigned number, [update the DID](../../inventory-resources/did/update-did.html).
- To cancel the entire service, [delete the Emergency Calling Service](delete-emergency-calling-service.html).

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Emergency Calling Services | `GET` | `/v3/emergency_calling_services` |
| Retrieve Emergency Calling Service | `GET` | `/v3/emergency_calling_services/{id}` |
| Delete Emergency Calling Service | `DELETE` | `/v3/emergency_calling_services/{id}` |

## Retrieve all Emergency Calling Services

Retrieves all Emergency Calling Services in the account.

Use this endpoint to find services by status, country, DID Group Type, registered Address,
Identity, name, or reference. The Address and Identity filters use the records from the last
Emergency Verification linked to each service.

Results can be sorted by name, status, country name, renewal date, or creation time. Sorting
by `renew_date` excludes canceled services.

The response can include the related country, DID Group Type, Order, Emergency Requirement,
Emergency Verification, and DIDs.

See [Retrieve All Emergency Calling Services](get-emergency-calling-services.html).

```
GET /v3/emergency_calling_services
```

## Retrieve Emergency Calling Service

Retrieves a specific Emergency Calling Service by its unique ID.

Use this endpoint to inspect the current service status, activation and renewal dates,
pricing, assigned DIDs, applicable Emergency Requirement, latest verification, and related
Order. Include the required relationships when the linked records are needed in the same
response.

See [Retrieve Emergency Calling Service](get-emergency-calling-service.html).

```
GET /v3/emergency_calling_services/{id}
```

## Delete Emergency Calling Service

Cancels a specific Emergency Calling Service.

Cancellation is allowed when the service status is `new`, `changes_required`,
`active`, or `pending_update`. A successful request returns `204 No Content` and the
service becomes permanently canceled.

See [Delete Emergency Calling Service](delete-emergency-calling-service.html).

```
DELETE /v3/emergency_calling_services/{id}
```

## Service lifecycle

### Create a service

To create a service, first select eligible DIDs and satisfy the applicable Emergency
Requirement. Then [create an Emergency Verification](../emergency-verifications/create-emergency-verification.html) in
**New Calling Service** mode
with the validated `address` and one or more `dids` relationships. Do not provide an
`emergency_calling_service` relationship in this mode.

The verification creates the Emergency Calling Service automatically. The DIDWW Emergency
Team reviews the submission. When the verification is approved and the service status
becomes `active`, emergency routing is enabled for the assigned DIDs.

Important

Do not create an Order to purchase emergency calling. DIDWW creates the related Order
automatically when the Emergency Calling Service is activated. This activation also
triggers the related Order callback.

### Update the registered address

An address update can be submitted when the service status is `new`,
`changes_required`, or `active`. 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 a `dids` relationship in this
mode.

For an active service, the status becomes `pending_update` while the new address is
reviewed. Emergency routing remains enabled with the current address during the review. The
replacement address takes effect only after approval, when the service returns to
`active`.

An update request returns `422 Unprocessable Entity` when the service is `in_process`,
`pending_update`, or `canceled`. If the verification is rejected, inspect its
`reject_reasons` and `reject_comment`, correct the data, and submit another verification.

### Manage assigned DIDs

Adding or removing DIDs is handled through [Update DID](../../inventory-resources/did/update-did.html), not through
Emergency Verification creation.
Use the DID's `emergency_calling_service` relationship to manage its assignment.

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.

## Status values

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

## Service data

The service provides:

- `name` and `reference` for identifying the service.
- `status` for tracking its lifecycle.
- `activated_at` and `canceled_at` timestamps. These can be `null` when the
  corresponding event has not occurred.
- `renew_date` for the next service renewal. This can be `null`.
- `created_at` for the service creation time.
- `meta.setup_price` and `meta.monthly_price` for its pricing.

See [Emergency Calling Service Object](emergency-calling-service-object.html) for all
attributes, metadata, and relationships.

## Common Emergency Calling Service use cases

| Use case | Description |
| --- | --- |
| Monitor activation | Filter services by status and retrieve the related Emergency Verification to track review and activation. |
| Find services by coverage | Filter services by country ID or DID Group Type ID. |
| Find a customer's service | Filter by the Identity or Address used in the last Emergency Verification. |
| Review assigned numbers | Include the related DIDs to see which phone numbers use the service. |
| Review registration rules | Include the related Emergency Requirement to inspect the rules that apply to the service and any future address update. |
| Review billing information | Include the automatically created Order and inspect the service's setup and monthly price metadata. |
| Update the emergency address | Submit an Emergency Verification in Existing Calling Service mode and monitor the service while it is `pending_update`. |
| Cancel emergency calling | Delete an eligible service when emergency routing and future renewal are no longer required. |

## Related resources

- [Emergency Resources](../index.html) - Follow the complete emergency calling
  registration and service-management workflow.
- [Emergency Requirements](../emergency-requirements/index.html) - Determine the Identity,
  Address, restriction, and pricing rules that apply to the service.
- [Emergency Verifications](../emergency-verifications/index.html) - Create a service,
  submit an address update, and inspect approval or rejection details.
- [DIDs](../../inventory-resources/did/index.html) - Retrieve assigned numbers and manage
  their Emergency Calling Service relationships.
- [Orders](../../inventory-resources/order/index.html) - Retrieve the Order created
  automatically when the service is activated.
- [Outbound Trunks](../../inventory-resources/voice-out-trunks/index.html) - Configure
  outbound routing for emergency-enabled DIDs after activation.
- [Callbacks Details](../../callbacks-details.html) - Handle Emergency Verification and
  related Order status notifications.

On this page