# 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](../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).

## Before creating a verification

- Use [Retrieve Address Requirements](../requirements/get-address-requirements.html) to identify the requirement for the DID's
  country and DID Group Type.
- Create or reuse an [Identity](../identities/index.html) and an [Address](../addresses/index.html) that satisfy the selected requirement.
- Add the required Identity and Address Proofs and any permanent supporting documents.
- Use [Address Requirement Validation](../requirements/address-requirement-validations.html) 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-address-verifications.html).

```
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-address-verification.html).

```
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](create-address-verification.html) and [Callbacks
Details](../../callbacks-details.html).

```
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](update-address-verification.html).

```
PATCH /v3/address_verifications/{id}
```

## Data reference

See [Address Verifications Object](address-verifications-object.html) 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](create-address-verification.html).

## 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](../requirements/index.html) - Determine which Identity, Address,
  Proofs, supporting documents, and service description are required.
- [Addresses](../addresses/index.html) - Retrieve or create the Address linked to the
  verification task.
- [Identities](../identities/index.html) - Manage the end-user Identity connected through
  the Address.
- [DIDs](../../inventory-resources/did/index.html) - Retrieve purchased numbers and check
  `awaiting_registration`.
- [Encrypted Files](../encrypted-files/index.html) - Upload encrypted one-time supporting
  documents before creating the verification.
- [Proofs](../proofs/index.html) - Link accepted evidence to the Identity or Address.
- [Permanent Supporting Documents](../permanent-documents/index.html) - Link reusable
  supporting documents to the Identity.
- [Callbacks Details](../../callbacks-details.html) - Process Address Verification status
  notifications.

On this page