Address Verifications

Use the Address Verifications resource to submit DID registration data for compliance review and monitor the result.

An Address Verification links one or more purchased DIDs to the Address prepared for the end user. The Identity is connected through that Address. The task can also include one-time Encrypted Files and a service description when required by the applicable Address Requirement.

All Address Verifications are reviewed by the DIDWW Compliance Team. A newly created task has a pending status and later becomes approved or rejected. You can retrieve the task to monitor its status or configure a callback when creating it.

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.

Before creating a verification

• Use Retrieve Address Requirements to identify the requirement for the DID’s country and DID Group Type.

• Create or reuse an Identity and an Address that satisfy the selected requirement.

• Add the required Identity and Address Proofs and any permanent supporting documents.

• Use Address Requirement Validation to identify missing or invalid data before submitting the verification.

• Include onetime_files only when the requirement references a personal or business one-time Supporting Document Template.

• Include service_description only when service_description_required is true. Supplying a one-time document or service description when it is not needed can cause a 422 Unprocessable Entity response.

Endpoints

Action	Method	Endpoint
Retrieve all Address Verifications	GET	/v3/address_verifications
Retrieve Address Verification	GET	/v3/address_verifications/{id}
Create Address Verification	POST	/v3/address_verifications
Update Address Verification	PATCH	/v3/address_verifications/{id}

Retrieve all Address Verifications

Retrieves all Address Verifications associated with the account.

Use this endpoint to monitor multiple verification tasks. Results can be filtered by Address ID, Identity ID, status, reference, or external reference ID and sorted by creation time or external reference ID. Related Addresses, DIDs, and DID Groups can be included in the response.

See Retrieve All Address Verifications.

GET /v3/address_verifications

Retrieve Address Verification

Retrieves a specific Address Verification by its unique ID.

Use this endpoint to inspect the current status and reference. For a rejected task, review reject_reasons and reject_comment to determine what must be corrected. The related Address, DIDs, and DID Groups can be included in the response.

See Retrieve Address Verification.

GET /v3/address_verifications/{id}

Create Address Verification

Creates an Address Verification and submits it for compliance review.

Link the DIDs being registered and the Address prepared for the end user. When required, also link one-time Encrypted Files and provide a service description. You may set external_reference_id to associate the task with an external system and configure callback_url and callback_method to receive the final status.

The callback method can be get or post. Callback notifications report an approved or rejected status and include rejection information when applicable.

See Create Address Verification and Callbacks Details.

POST /v3/address_verifications

Update Address Verification

Updates the external_reference_id of an existing Address Verification.

No other Address Verification attributes or relationships can be changed with this endpoint. The external reference ID is optional and has a maximum length of 100 characters.

See Update Address Verification.

PATCH /v3/address_verifications/{id}

Data reference

See Address Verifications Object for all attributes and relationships returned by the resource.

Verification statuses

Status	Meaning
pending	The verification has been submitted and is awaiting compliance review.
approved	The submitted registration data has been approved.
rejected	The submitted registration data was not approved. Inspect reject_reasons and reject_comment for details.

Sandbox testing

In the sandbox environment, you can simulate the result by setting id_number on the Identity linked through the Address:

Result	id_number value
Approve	11111111-1111-1111-1111-111111111111
Reject	22222222-2222-2222-2222-222222222222

See the testing instructions on Create Address Verification.

Common Address Verification use cases

Use case	Description
Submit DID registration data	Link purchased DIDs to the prepared Address and submit them for compliance review.
Provide one-time documents	Link completed and encrypted one-time forms when the Address Requirement calls for them.
Provide a service description	Describe the intended DID service when service_description_required is true.
Monitor verification progress	Filter tasks by status or reference, or retrieve a specific task by its ID.
Resolve a rejection	Inspect reject_reasons and reject_comment to determine which data or documents must be corrected before creating a new submission.
Receive status notifications	Configure a callback to receive the approved or rejected result without polling.
Reconcile external records	Create, filter, sort, or update tasks using external_reference_id.
Test an integration	Simulate approval and rejection outcomes in the sandbox environment.

Related resources

• Address Requirements — Determine which Identity, Address, Proofs, supporting documents, and service description are required.

• Addresses — Retrieve or create the Address linked to the verification task.

• Identities — Manage the end-user Identity connected through the Address.

• DIDs — Retrieve purchased numbers and check awaiting_registration.

• Encrypted Files — Upload encrypted one-time supporting documents before creating the verification.

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

• Permanent Supporting Documents — Link reusable supporting documents to the Identity.

• Callbacks Details — Process Address Verification status notifications.