# Emergency Requirements

Use the Emergency Requirements resource to retrieve the emergency calling registration
conditions available for DID phone numbers in the DIDWW coverage catalog.

An Emergency Requirement applies to a particular country and DID Group Type. It defines
the permitted Identity type, Identity and Address location scopes, mandatory fields,
estimated activation time, additional restrictions, and emergency calling pricing.

Emergency Requirements are read-only. Retrieve the applicable requirement before creating
or reusing an Identity and Address. After preparing those records, use an Emergency
Requirement Validation to check them before creating an Emergency Verification.

Note

For the complete registration and service-management workflow, see [Emergency
Resources](../index.html). For an end-to-end example, see [Register Emergency Calling
Service](../../../examples/register-emergency-calling-service.html).

## Selecting the applicable requirement

Use [Retrieve All DIDs](../../inventory-resources/did/get-dids.html) to select active DIDs
whose DID Groups support the `emergency` feature. The DIDs submitted together must have
the same country and DID Group Type.

Use those related IDs to filter Emergency Requirements by `country.id` and
`did_group_type.id`. Inspect the selected requirement before creating any dependent
records:

- `identity_type` determines whether a personal Identity, business Identity, or either
  type can be used.
- `personal_area_level` and `business_area_level` determine whether the applicable
  Identity can be worldwide or must be from the requirement country. A value can be
  `null` when that Identity type does not apply.
- `address_area_level` determines whether the Address must be in the requirement country,
  the locality or region covered by the DID prefix, or the same city as the DID.
- `personal_mandatory_fields` and `business_mandatory_fields` identify additional
  Identity data that must be supplied.
- `address_mandatory_fields` identifies additional Address data that must be supplied.
- `estimate_setup_time` provides the estimated service activation time.
- `requirement_restriction_message` provides additional instructions for the selected
  country and DID Group Type.
- `meta.setup_price` and `meta.monthly_price` provide the applicable emergency service
  pricing.

If a selected DID already has approved end-user registration, use an Address linked to the
same Identity for emergency registration. Include the DID's `identity` and
`address_verification` relationships when retrieving it to identify this condition.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Emergency Requirements | `GET` | `/v3/emergency_requirements` |
| Retrieve Emergency Requirement | `GET` | `/v3/emergency_requirements/{id}` |
| Validate an Identity or Address | `POST` | `/v3/emergency_requirement_validations` |

## Retrieve all Emergency Requirements

Retrieves all Emergency Requirements available to the account.

Use this endpoint to find the requirement that applies to the selected DIDs. Results can be
filtered by Emergency Requirement ID, country ID, or DID Group Type ID. The country and DID
Group Type records can be included in the response.

See [Retrieve All Emergency Requirements](get-emergency-requirements.html).

```
GET /v3/emergency_requirements
```

## Retrieve Emergency Requirement

Retrieves a specific Emergency Requirement by its unique ID.

Use this endpoint when the applicable requirement is already known and you need to inspect
its attributes, pricing, country, or DID Group Type before validation or submission.

See [Retrieve Emergency Requirement](get-emergency-requirement.html).

```
GET /v3/emergency_requirements/{id}
```

## Validate an Identity or Address

Checks whether an Identity, Address, or both satisfy a selected Emergency Requirement.

Use this endpoint after preparing the required records and before creating an Emergency
Verification. Link the Emergency Requirement and the applicable Identity, Address, or both
to be checked. A successful request returns `201 Created`. A `422 Unprocessable Entity`
response lists missing or invalid data that should be corrected before submission.

See [Validate an Emergency Requirement](emergency-requirement-validations.html).

```
POST /v3/emergency_requirement_validations
```

## Access and pricing

Access to these endpoints requires an emergency calling plan assigned to the account. A
request returns `403 Forbidden` when no plan is assigned.

The pricing values are returned in the resource's `meta` object:

| Field | Meaning |
| --- | --- |
| `setup_price` | One-time setup price as a decimal string. The value is always `0.0` when a matching rate exists because activation is not charged through this API. It can be `null` when no matching emergency plan rate exists. |
| `monthly_price` | Monthly price from the account's matching emergency plan rate as a decimal string. It can be `null` when no matching rate exists. |

## Requirement scope

### Identity type

The `identity_type` attribute can contain:

| Value | Meaning |
| --- | --- |
| `personal` | A personal Identity is required. |
| `business` | A business Identity is required. |
| `any` | A personal or business Identity can be used. |

### Identity location

The applicable `personal_area_level` or `business_area_level` attribute can contain:

| 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 can contain:

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

## Data reference

See [Emergency Requirement Object](emergency-requirement-object.html) for all attributes,
metadata, relationships, and supported values returned by the resource. See
[Emergency Requirement Validations](emergency-requirement-validations.html) for the
validation request relationships and response examples.

## Common Emergency Requirement use cases

| Use case | Description |
| --- | --- |
| Find a requirement for selected DIDs | Filter Emergency Requirements by the common country ID and DID Group Type ID of the selected DIDs. |
| Select an Identity type | Use `identity_type` to determine whether a personal Identity, business Identity, or either type can be used. |
| Apply location restrictions | Use the Identity and Address area-level attributes to select records from an accepted country, locality, region, or city. |
| Prepare mandatory data | Supply every field listed in the applicable personal, business, and Address mandatory field arrays. |
| Show activation guidance | Present `estimate_setup_time` and `requirement_restriction_message` before the customer submits emergency registration data. |
| Show service pricing | Present the setup and monthly prices returned for the account's matching emergency plan rate. |
| Check submission readiness | Create an Emergency Requirement Validation to find missing or invalid Identity and Address data before creating an Emergency Verification. |

## Related resources

- [Emergency Resources](../index.html) - Follow the complete emergency calling
  registration and service-management workflow.
- [DIDs](../../inventory-resources/did/index.html) - Select active emergency-capable
  numbers and retrieve their country, DID Group Type, and existing registration
  relationships.
- [DID Groups](../../coverage-resources/did-group/index.html) - Check whether the DID Group
  supports the `emergency` feature.
- [Countries](../../coverage-resources/countries/index.html) - Retrieve the country used to
  filter Emergency Requirements.
- [DID Group Types](../../coverage-resources/did-group-type/index.html) - Retrieve the DID
  service type used to filter Emergency Requirements.
- [Identities](../../regulation-resources/identities/index.html) - Create or retrieve the
  personal or business Identity required by the selected requirement.
- [Addresses](../../regulation-resources/addresses/index.html) - Create or retrieve the
  emergency location linked to the selected Identity.
- [Emergency Verifications](../emergency-verifications/index.html) - Submit the validated
  Address and selected DIDs for review.

On this page