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.

• To prepare compliance data, create an Identity and create an Address, or retrieve records that can be reused.

• To check the prepared records before submission, create an Address Requirement Validation.

• To submit DIDs for compliance review, create an Address Verification.

• To monitor a submission, retrieve the Address Verification or configure a callback when creating it.

Resource overview

Resource	Use it to
Address Requirements	Determine the identity, location, proof, supporting-document, and service-description requirements for a country and DID Group Type.
Areas	Retrieve regulatory areas when a requirement restricts an address to the locality or region covered by a DID prefix.
Identities	Create and manage personal or business identity records for the end user.
Addresses	Create and manage addresses linked to an identity and country.
Proof Types	Retrieve proof categories accepted for personal identities, business identities, and addresses.
Public Keys	Retrieve the RSA public keys and fingerprint needed to encrypt documents before upload.
Encrypted Files	Upload temporary encrypted files for proofs and supporting documents.
Proofs	Link encrypted files and an accepted Proof Type to an Identity or Address.
Supporting Document Templates	Retrieve forms required by a regulation and identify whether each form is permanent or one-time.
Permanent Supporting Documents	Link completed reusable supporting documents to an Identity.
Address Requirement Validations	Check an Identity and Address against an Address Requirement before creating a verification task.
Address Verifications	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.

1. Identify the applicable requirement

Use Retrieve All DID Groups to check needs_registration. For purchased numbers, use Retrieve All DIDs to check awaiting_registration.

Use Retrieve Address Requirements 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 and Retrieve All Addresses to find records that can be reused. If suitable records do not exist, create a personal or business Identity, then create an Address 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 when you need the details of an accepted type. For every required proof:

1. Retrieve the current Public Keys and encrypt the source document as described in Encryption Details.

2. Create an Encrypted File with the file and its encryption fingerprint.

3. Create a Proof 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, download the required form from its url, complete it, encrypt it, and upload it as an Encrypted File.

• For a permanent template, create a Permanent Supporting Document 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. Do not create a Permanent Supporting Document for a one-time file.

5. Validate the prepared records

Create an Address Requirement Validation 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 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 to inspect the status, reject_reasons, and reject_comment, or use Retrieve All Address Verifications 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.

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 — Find DID Groups, determine whether registration is required, and identify the country and DID Group Type.

• Inventory Resources — Create orders and retrieve purchased DIDs that may be awaiting registration.

• Emergency Resources — Manage the separate verification workflow for emergency calling services.

• Callbacks Details — Handle Address Verification status notifications.