# Regulation Resources

Use Regulation Resources to identify and satisfy end-user registration requirements for
DID phone numbers through the DIDWW API.

Registration requirements depend on the country and DID Group Type. A DID Group indicates
whether registration is required through its `needs_registration` attribute, while a
purchased DID may remain in the `awaiting_registration` state until its registration is
approved.

Start with the endpoint that matches your current task:

- To discover what is required, [retrieve Address Requirements](requirements/get-address-requirements.html).
- To prepare compliance data, [create an Identity](identities/create-identity.html) and
  [create an Address](addresses/create-address.html), or retrieve records that can be
  reused.
- To check the prepared records before submission, create an
  [Address Requirement Validation](requirements/address-requirement-validations.html).
- To submit DIDs for compliance review, [create an Address Verification](address-verifications/create-address-verification.html).
- To monitor a submission, [retrieve the Address Verification](address-verifications/get-address-verification.html) or configure a callback when creating
  it.

## Resource overview

| Resource | Use it to |
| --- | --- |
| [Address Requirements](requirements/index.html) | Determine the identity, location, proof, supporting-document, and service-description requirements for a country and DID Group Type. |
| [Areas](areas/index.html) | Retrieve regulatory areas when a requirement restricts an address to the locality or region covered by a DID prefix. |
| [Identities](identities/index.html) | Create and manage personal or business identity records for the end user. |
| [Addresses](addresses/index.html) | Create and manage addresses linked to an identity and country. |
| [Proof Types](proof-types/index.html) | Retrieve proof categories accepted for personal identities, business identities, and addresses. |
| [Public Keys](encrypted-files/public-keys.html) | Retrieve the RSA public keys and fingerprint needed to encrypt documents before upload. |
| [Encrypted Files](encrypted-files/index.html) | Upload temporary encrypted files for proofs and supporting documents. |
| [Proofs](proofs/index.html) | Link encrypted files and an accepted Proof Type to an Identity or Address. |
| [Supporting Document Templates](supporting-document-templates/index.html) | Retrieve forms required by a regulation and identify whether each form is permanent or one-time. |
| [Permanent Supporting Documents](permanent-documents/index.html) | Link completed reusable supporting documents to an Identity. |
| [Address Requirement Validations](requirements/address-requirement-validations.html) | Check an Identity and Address against an Address Requirement before creating a verification task. |
| [Address Verifications](address-verifications/index.html) | Submit DIDs and compliance records for review, then retrieve their status and any rejection details. |

## Common workflow

A typical registration workflow starts with the DID Group and narrows the applicable
requirement before any compliance records or documents are submitted.

```
DID Group (needs_registration = true)
 └─ Address Requirement (Country + DID Group Type)
    ├─ Identity
    │  ├─ Address
    │  ├─ Proofs, when required
    │  └─ Permanent Supporting Documents, when required
    ├─ One-time Supporting Documents, when required
    ├─ Address Requirement Validation
    └─ Address Verification
       └─ pending → approved or rejected
```

Note

For a complete step-by-step example that covers discovering inventory, ordering a DID,
preparing compliance records, and submitting the verification, see [Buy a DID
Number That Requires Verification](../../examples/buy-dids-with-verification.html).

### 1. Identify the applicable requirement

Use [Retrieve All DID Groups](../coverage-resources/did-group/get-did-groups.html) to
check `needs_registration`. For purchased numbers, use [Retrieve All DIDs](../inventory-resources/did/get-dids.html) to
check `awaiting_registration`.

Use [Retrieve Address Requirements](requirements/get-address-requirements.html) and filter
the results by the DID Group's `country.id` and `did_group_type.id`. Inspect the
returned requirement before creating any dependent records, especially:

- `identity_type` and the personal or business area level.
- `address_area_level` and any related regulatory area.
- `personal_proof_qty`, `business_proof_qty`, or `address_proof_qty`.
- The related personal, business, and address Proof Types.
- `personal_mandatory_fields` or `business_mandatory_fields`.
- Permanent and one-time Supporting Document Template relationships.
- `service_description_required` and `restriction_message`.

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.

### 2. Create or reuse the Identity and Address

Use [Retrieve All Identities](identities/get-identities.html) and [Retrieve All
Addresses](addresses/get-addresses.html) to find records that can be reused. If suitable records
do not exist, [create a personal or business Identity](identities/create-identity.html),
then [create an Address](addresses/create-address.html) linked to that Identity and the
required country. Supply every field listed in the applicable requirement's mandatory field
arrays.

In API version `2026-04-16`, assigning `country` to an Identity does not automatically
assign `birth_country`. Set `birth_country` explicitly when the requirement needs it.

Once approved, an Identity and Address may be reused for other DID types that have the same
level of restrictions.

### 3. Add proofs when required

Use the proof quantities and related Proof Types in the Address Requirement to determine
how many proofs are needed and which types are accepted. Use [Retrieve All Proof
Types](proof-types/get-proof-types.html) when you need the details of an accepted type. For every
required proof:

1. [Retrieve the current Public Keys](encrypted-files/public-keys.html) and encrypt the
   source document as described in [Encryption Details](encrypted-files/encryption-details.html).
2. [Create an Encrypted File](encrypted-files/create-encrypted-files.html) with the file
   and its encryption fingerprint.
3. [Create a Proof](proofs/create-proof.html) that links the Encrypted File, the accepted
   Proof Type, and the relevant Identity or Address.

Important

`POST /v3/encrypted_files` accepts one encrypted `.pdf`, `.jpg`, or `.png` file
per request. The file must not exceed 20 MB and expires 24 hours after upload, so use the
returned Encrypted File ID before it expires.

### 4. Add supporting documents when required

An Address Requirement may reference a personal or business Supporting Document Template.
Use [Retrieve All Supporting Document Templates](supporting-document-templates/get-supporting-document-templates.html),
download the required
form from its `url`, complete it, encrypt it, and [upload it as an Encrypted
File](encrypted-files/create-encrypted-files.html).

- For a **permanent** template, [create a Permanent Supporting Document](permanent-documents/create-permanent-document.html) that links the Encrypted File, template,
  and Identity. It can be reused with that Identity where the same permanent document is
  required.
- For a **one-time** template, pass the Encrypted File ID in the `onetime_files`
  relationship when [creating the Address Verification](address-verifications/create-address-verification.html). Do not
create a Permanent Supporting
  Document for a one-time file.

### 5. Validate the prepared records

[Create an Address Requirement Validation](requirements/address-requirement-validations.html) with the Address Requirement, Identity, and
Address IDs. A successful response confirms that those records satisfy the selected
requirement. A `422 Unprocessable Entity` response identifies missing or invalid
information that should be corrected before submission.

### 6. Submit and monitor the verification

[Create an Address Verification](address-verifications/create-address-verification.html)
that links the DIDs and Address. Include one-time Encrypted Files and a service description
only when required. The Identity is connected through the Address.

All Address Verifications are reviewed by the DIDWW Compliance Team. The verification status
can be `pending`, `approved`, or `rejected`. Use [Retrieve Address
Verification](address-verifications/get-address-verification.html) to inspect the status, `reject_reasons`,
and `reject_comment`, or use [Retrieve All Address Verifications](address-verifications/get-address-verifications.html)
to monitor multiple submissions. You can
also set `callback_url` and `callback_method` when creating the verification to receive
approved or rejected status notifications. See [Callbacks Details](../callbacks-details.html).

## Requirement scope

Address Requirements can restrict where the Identity or Address must be located.

### Identity location

The `personal_area_level` and `business_area_level` attributes support:

| 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 supports:

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

## Related resources

- [Coverage Resources](../coverage-resources/index.html) - Find DID Groups, determine
  whether registration is required, and identify the country and DID Group Type.
- [Inventory Resources](../inventory-resources/index.html) - Create orders and retrieve
  purchased DIDs that may be awaiting registration.
- [Emergency Resources](../emergency-resources/index.html) - Manage the separate
  verification workflow for emergency calling services.
- [Callbacks Details](../callbacks-details.html) - Handle Address Verification status
  notifications.

On this page