# Areas

Use the Areas resource to retrieve regulatory geographic areas used by DID registration
requirements.

An Area represents a locality or region within a country for regulatory purposes. It
provides a name and a country relationship. When an Address Requirement has
`address_area_level` set to `area`, the Address used for verification must be within the
locality or region covered by the DID phone number's prefix.

Areas are read-only and are separate from the Regions resource in Coverage Resources. Use
Areas to interpret registration restrictions. Use Coverage Regions to search DID inventory
by geographic subdivision.

Note

For the complete registration workflow, see [Regulation Resources](../index.html). For
an end-to-end purchasing and verification example, see [Buy a DID Number That
Requires Verification](../../../examples/buy-dids-with-verification.html).

## When to use Areas

Inspect the applicable [Address Requirement](../requirements/index.html) before selecting
an Address:

| Address area level | Address restriction |
| --- | --- |
| `world_wide` | An Address from any country can be used. An Area lookup is not required. |
| `country` | The Address must be within the requirement country. An Area lookup is not required. |
| `area` | The Address must be within the locality or region covered by the DID prefix. Use the Areas resource to identify the regulatory area. |
| `city` | The Address must be from the same City as the DID. Use the Cities resource instead. |

For an area-level requirement, identify the DID's country and prefix from its DID Group,
then retrieve Areas by country ID and name. Prepare an Address within the matching
regulatory area and validate it against the Address Requirement before creating an Address
Verification.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Areas | `GET` | `/v3/areas` |
| Retrieve Area | `GET` | `/v3/areas/{id}` |

## Retrieve all Areas

Retrieves all regulatory Areas available through the DIDWW API.

Use this endpoint to find Areas by ID, case-insensitive name, or country ID. Results can be
sorted by name and can include the related country. Both the default and maximum page size
are 1,000 records.

See [Retrieve All Areas](get-areas.html).

```
GET /v3/areas
```

## Retrieve Area

Retrieves a specific regulatory Area by its unique ID.

Use this endpoint when the Area ID is already known and you need to inspect its name or
include its related country.

See [Retrieve Area](get-area.html).

```
GET /v3/areas/{id}
```

## Data reference

See [Area Object](area-object.html) for all attributes and relationships returned by the
resource.

## Common Area use cases

| Use case | Description |
| --- | --- |
| Satisfy an area-level requirement | Identify the locality or region in which an Address must be located when `address_area_level` is `area`. |
| Find Areas in a country | Filter by `country.id` to retrieve regulatory Areas for the requirement country. |
| Find an Area by name | Use the case-insensitive `name` filter to resolve a regulatory Area and its ID. |
| Confirm an Area's country | Include the related country when retrieving one or more Areas. |
| Review an Address relationship | Use an Area ID when filtering Addresses or inspect the Area included with an Address. |
| Prepare registration data | Select an Address within the required Area before running an Address Requirement Validation. |

## Related resources

- [Address Requirements](../requirements/index.html) - Determine whether the Address must
  be within the DID's regulatory Area.
- [DID Groups](../../coverage-resources/did-group/index.html) - Identify the DID country,
  area name, and prefix associated with the registration requirement.
- [Addresses](../addresses/index.html) - Create or retrieve an Address that satisfies the
  area-level restriction.
- [Countries](../../coverage-resources/countries/index.html) - Retrieve country records
  related to Areas.
- [Cities](../../coverage-resources/city/index.html) - Retrieve coverage Cities for
  requirements where `address_area_level` is `city`.
- [Regions](../../coverage-resources/regions/index.html) - Retrieve coverage Regions used
  for DID inventory searches rather than regulatory Area restrictions.
- [Address Requirement Validation](../requirements/address-requirement-validations.html) - Check the prepared Identity and
  Address against the selected requirement.
- [Address Verifications](../address-verifications/index.html) - Submit the prepared DIDs
  and Address for compliance review.

On this page