# Address Requirements

Use the Address Requirements resource to retrieve the registration conditions that apply
to DID phone numbers in the DIDWW coverage catalog.

An Address Requirement defines the compliance data needed for a particular country and DID
Group Type. It specifies the permitted Identity type, Identity and Address location scopes,
mandatory Identity fields, required proof quantities and accepted Proof Types, required
supporting documents, and whether a service description is needed.

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

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

## Selecting the applicable requirement

Use [Retrieve All DID Groups](../../coverage-resources/did-group/get-did-groups.html) to check `needs_registration` and
identify the DID Group's country and DID Group Type. You can include the DID Group's related
`address_requirement` or retrieve Address Requirements filtered by `country.id` and
`did_group_type.id`.

Inspect the selected requirement before creating any dependent records:

- `identity_type` determines whether the end user may be personal, business, or either.
- `personal_area_level` and `business_area_level` determine whether the applicable
  Identity may be worldwide or must be from the requirement country.
- `address_area_level` determines whether the Address may be worldwide or must be within
  the requirement country, the DID's regulatory Area, or the same City as the DID.
- `personal_proof_qty`, `business_proof_qty`, and `address_proof_qty` specify how many
  Proofs are required.
- The related `personal_proof_types`, `business_proof_types`, and
  `address_proof_types` specify which Proof Types are accepted.
- `personal_mandatory_fields` and `business_mandatory_fields` identify additional
  Identity fields that must be supplied.
- The permanent and one-time Supporting Document Template relationships identify forms that
  must be completed and uploaded.
- `service_description_required` indicates whether a service description must be included
  in the Address Verification. `restriction_message` provides additional instructions for
  the selected country and DID Group Type.

Note

Proofs, supporting documents, and a service description are not required by every
regulation. Create or submit them only when the applicable Address Requirement calls for
them.

## Endpoints

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

## Retrieve all Address Requirements

Retrieves all Address Requirements available in the DIDWW coverage catalog.

Use this endpoint to find the requirement for a DID Group. Results can be filtered by
Address Requirement ID, country ID, or DID Group Type ID. Related country, DID Group Type,
Proof Type, and Supporting Document Template records can be included in the response.

See [Retrieve All Address Requirements](get-address-requirements.html).

```
GET /v3/address_requirements
```

## Retrieve Address Requirement

Retrieves a specific Address Requirement by its unique ID.

Use this endpoint when the applicable Address Requirement is already known and you need to
inspect its attributes or include its related Proof Types and Supporting Document Templates.

See [Retrieve Address Requirement](get-address-requirement.html).

```
GET /v3/address_requirements/{id}
```

## Validate an Identity or Address

Checks whether an Identity and/or Address satisfies a selected Address Requirement.

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

See [Validate an Address Requirement](address-requirement-validations.html).

```
POST /v3/address_requirement_validations
```

## Data reference

See [Address Requirement Object](address-requirement-object.html) for all attributes and
relationships returned by the resource. The [Retrieve All Address Requirements](get-address-requirements.html) page also
lists the values that may appear in the personal and
business mandatory field arrays.

## Requirement scope

### Identity location

The `personal_area_level` and `business_area_level` attributes 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 |
| --- | --- |
| `world_wide` | An Address from any country can be used. |
| `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 DID. |

## Common Address Requirement use cases

| Use case | Description |
| --- | --- |
| Determine whether registration is required | Check the DID Group's `needs_registration` value and retrieve its related Address Requirement when registration is needed. |
| Find a requirement by coverage | Filter Address Requirements by country ID and DID Group Type ID to identify the applicable compliance rules. |
| Select an Identity type | Use `identity_type` to determine whether a personal Identity, business Identity, or either type may be used. |
| Apply location restrictions | Use the Identity and Address area-level attributes to select records from an accepted country, regulatory Area, or City. |
| Prepare mandatory data | Supply all fields listed in the applicable personal or business mandatory field array. |
| Prepare proofs | Use the proof quantities and related Proof Types to determine how many proofs are required and which types are accepted. |
| Prepare supporting documents | Use the related permanent and one-time Supporting Document Templates to identify, complete, and upload required forms. |
| Check registration readiness | Create an Address Requirement Validation to find missing or invalid information before submitting an Address Verification. |

## Related resources

- [DID Groups](../../coverage-resources/did-group/index.html) - Determine whether
  registration is required and identify the applicable country and DID Group Type.
- [Identities](../identities/index.html) - Create or retrieve the personal or business
  Identity required by the selected requirement.
- [Addresses](../addresses/index.html) - Create or retrieve an Address that meets the
  required location scope.
- [Areas](../areas/index.html) - Retrieve regulatory Areas used by area-level address
  restrictions.
- [Proof Types](../proof-types/index.html) - Retrieve details about the proof categories
  accepted by the requirement.
- [Proofs](../proofs/index.html) - Link accepted evidence to an Identity or Address.
- [Supporting Document Templates](../supporting-document-templates/index.html) - Retrieve
  permanent or one-time forms referenced by the requirement.
- [Address Verifications](../address-verifications/index.html) - Submit the prepared DIDs
  and compliance data for review.

On this page