# Emergency Verifications

Use the Emergency Verifications resource to submit emergency calling registration data for
review and monitor the result.

An Emergency Verification links a validated Address either to one or more DIDs for a new
Emergency Calling Service or to an existing service whose registered address must be
replaced. The verification records its reference, review status, rejection details,
callback settings, creation time, external reference ID, and related resources.

All Emergency Verifications are reviewed by the DIDWW Emergency Team. A newly created
verification has a `pending` status and later becomes `approved` or `rejected`. You
can retrieve the verification to monitor its status or configure a callback when creating
it.

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

## Before creating a verification

- Confirm that the account has an emergency calling plan. Creation returns
  `403 Forbidden` when no plan is assigned.
- Use [Retrieve All DIDs](../../inventory-resources/did/get-dids.html) to select active
  DIDs whose DID Groups support the `emergency` feature.
- For a new service, confirm that the selected DIDs use the same country and DID Group Type
  and are not assigned to another Emergency Calling Service.
- Retrieve the applicable [Emergency Requirement](../emergency-requirements/get-emergency-requirements.html) using the selected country ID and
  DID Group Type ID.
- Create or reuse an Identity and Address that satisfy the Emergency Requirement. If a DID
  already has approved end-user registration, use an Address linked to the same Identity.
- Use [Emergency Requirement Validation](../emergency-requirements/emergency-requirement-validations.html) to identify missing or
  invalid Identity and Address data before submission.
- Choose either **New Calling Service** or **Existing Calling Service** mode. Do not combine
  the relationships used by the two modes.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Emergency Verifications | `GET` | `/v3/emergency_verifications` |
| Retrieve Emergency Verification | `GET` | `/v3/emergency_verifications/{id}` |
| Create Emergency Verification | `POST` | `/v3/emergency_verifications` |
| Update Emergency Verification | `PATCH` | `/v3/emergency_verifications/{id}` |

## Retrieve all Emergency Verifications

Retrieves all Emergency Verifications associated with the account.

Use this endpoint to monitor multiple verification tasks. Results can be filtered by
status, Emergency Calling Service ID, or external reference ID and sorted by creation time
or external reference ID. The related Address, Emergency Calling Service, and DIDs can be
included in the response.

See [Retrieve All Emergency Verifications](get-emergency-verifications.html).

```
GET /v3/emergency_verifications
```

## Retrieve Emergency Verification

Retrieves a specific Emergency Verification by its unique ID.

Use this endpoint to inspect the current status and reference. For a rejected verification,
review `reject_reasons` and `reject_comment` to determine what must be corrected. The
related Address, Emergency Calling Service, and DIDs can be included in the response.

See [Retrieve Emergency Verification](get-emergency-verification.html).

```
GET /v3/emergency_verifications/{id}
```

## Create Emergency Verification

Creates an Emergency Verification and submits it for review. A successful request returns
`201 Created` with a verification whose initial status is `pending`.

Choose the creation mode from the action you need to perform:

| Mode | Relationships to provide | Result |
| --- | --- | --- |
| New Calling Service | Provide `address` and one or more `dids`. Do not provide `emergency_calling_service`. | Creates a new Emergency Calling Service automatically and submits its registration for review. |
| Existing Calling Service | Provide `address` and `emergency_calling_service`. Do not provide `dids`. | Resubmits a rejected service or submits a replacement address for an existing service. |

You can also provide:

- `external_reference_id` to associate the verification with a record in an external
  system. Its maximum length is 100 characters.
- `callback_url` to receive the final review result.
- `callback_method` set to `get` or `post`. It is required when `callback_url` is
  provided.

See [Create Emergency Verification](create-emergency-verification.html).

```
POST /v3/emergency_verifications
```

## Update Emergency Verification

Updates the `external_reference_id` of a specific Emergency Verification.

No other verification attributes or relationships can be changed with this endpoint. The
external reference ID is optional and has a maximum length of 100 characters.

See [Update Emergency Verification](update-emergency-verification.html).

```
PATCH /v3/emergency_verifications/{id}
```

## Creation modes and service effects

### New Emergency Calling Service

Use this mode when the selected DIDs are not assigned to an Emergency Calling Service.
Provide the validated Address and at least one DID. The service is created automatically
and is linked in the successful verification response.

If the verification is approved, the Emergency Calling Service becomes `active` and
emergency routing is enabled for its DIDs. If it is rejected, the service becomes
`changes_required`. Correct the rejected data and create a new verification in **Existing
Calling Service** mode.

Important

Do not create an Order to purchase emergency calling. When the Emergency Calling Service
is activated, DIDWW creates its related Order automatically and triggers the related
Order callback.

### Existing Emergency Calling Service

Use this mode to resubmit a service in `changes_required` or to replace the registered
address of a service whose status is `new` or `active`. Provide the replacement Address
and existing Emergency Calling Service. Do not provide DIDs in this mode.

For an active service, its status becomes `pending_update` during review. Emergency
routing remains enabled with the current address. The replacement address takes effect
only if the verification is approved and the service returns to `active`.

The request returns `422 Unprocessable Entity` if the service status is `in_process`,
`pending_update`, or `canceled`.

## Common creation errors

A `422 Unprocessable Entity` response can identify one or more issues that must be fixed,
including:

- No DIDs were supplied in New Calling Service mode.
- A matching emergency plan rate was not found.
- The selected DIDs do not share the same DID Group Type.
- A DID does not support the `emergency` feature.
- A DID that requires city-level data is not linked to a City ID.
- A DID is already assigned to another Emergency Calling Service.
- The Address or its Identity does not satisfy the applicable Emergency Requirement.
- A DID with approved end-user registration is submitted with an Address linked to a
  different Identity.

Use [Emergency Requirement Validation](../emergency-requirements/emergency-requirement-validations.html) before creation
to detect
Identity and Address problems early. DID-specific and rate checks are still applied when
the Emergency Verification is created.

## Verification statuses

| Status | Meaning |
| --- | --- |
| `pending` | The verification has been submitted and is awaiting a decision from the DIDWW Emergency Team. |
| `approved` | The submitted emergency registration data has been approved. |
| `rejected` | The submitted data was not approved. Inspect `reject_reasons` and `reject_comment` for details. |

## Callbacks

When a callback is configured, DIDWW sends a notification after the verification becomes
`approved` or `rejected`. The payload contains the verification ID, resource type,
status, rejection information, and related Emergency Calling Service ID.

A `get` callback sends the payload as query parameters. A `post` callback sends it as
`application/x-www-form-urlencoded` data. See [Callbacks Details](../../callbacks-details.html) for all parameters and
request-signature validation.

## Data reference

See [Emergency Verification Object](emergency-verification-object.html) for all attributes
and relationships returned by the resource.

## Common Emergency Verification use cases

| Use case | Description |
| --- | --- |
| Create an emergency service | Submit a validated Address and compatible DIDs in New Calling Service mode. |
| Resubmit rejected data | Correct the reported problems and create a new verification for the service in `changes_required`. |
| Replace a registered address | Submit a validated replacement Address for an existing service and monitor its `pending_update` state. |
| Monitor review progress | Filter verifications by status or Emergency Calling Service ID, or retrieve a specific verification. |
| Resolve a rejection | Inspect `reject_reasons` and `reject_comment` to determine which data must be corrected before resubmission. |
| Receive status notifications | Configure a callback to receive the approved or rejected result without polling. |
| Reconcile external records | Create, filter, sort, or update verifications using `external_reference_id`. |

## Related resources

- [Emergency Resources](../index.html) - Follow the complete emergency calling
  registration and service-management workflow.
- [Emergency Requirements](../emergency-requirements/index.html) - Determine and validate
  the Identity and Address rules for the selected DIDs.
- [Emergency Calling Services](../emergency-calling-services/index.html) - Retrieve the
  service created or updated by the verification.
- [Addresses](../../regulation-resources/addresses/index.html) - Create or retrieve the
  emergency location submitted for review.
- [Identities](../../regulation-resources/identities/index.html) - Manage the Identity
  linked through the submitted Address.
- [DIDs](../../inventory-resources/did/index.html) - Select compatible phone numbers and
  manage their Emergency Calling Service assignments.
- [Orders](../../inventory-resources/order/index.html) - Retrieve the Order created
  automatically when the Emergency Calling Service is activated.
- [Callbacks Details](../../callbacks-details.html) - Process Emergency Verification and
  related Order status notifications.

On this page