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. For an end-to-end purchasing and verification example, see Buy a DID Number That Requires Verification.

Selecting the applicable requirement

Use Retrieve All DID Groups 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 /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 /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.

POST /v3/address_requirement_validations

Data reference

See Address Requirement Object for all attributes and relationships returned by the resource. The Retrieve All Address Requirements 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 — Determine whether registration is required and identify the applicable country and DID Group Type.

• Identities — Create or retrieve the personal or business Identity required by the selected requirement.

• Addresses — Create or retrieve an Address that meets the required location scope.

• Areas — Retrieve regulatory Areas used by area-level address restrictions.

• Proof Types — Retrieve details about the proof categories accepted by the requirement.

• Proofs — Link accepted evidence to an Identity or Address.

• Supporting Document Templates — Retrieve permanent or one-time forms referenced by the requirement.

• Address Verifications — Submit the prepared DIDs and compliance data for review.