# Addresses

Use the Addresses resource to retrieve and manage address records used for DID registration
and verification.

An Address represents the physical location associated with an Identity. It stores the city
name, postal code, and full address and is linked to an Identity and country. It can also be
related to Proofs, a regulatory Area, and a City. The `verified` attribute indicates
whether the Address has been verified.

Before creating an Address, retrieve the applicable [Address Requirement](../requirements/index.html). Its
`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.

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

## Requirements and behavior

- `city_name`, `postal_code`, and `address` are required when creating an Address.
- The Address must be linked to the relevant Identity and country.
- The location must satisfy the Address Requirement's `address_area_level` value. Possible
  values are `world_wide`, `country`, `area`, and `city`.
- Proofs can be linked to the Address when `address_proof_qty` is greater than zero. Use
  the Address Requirement's `address_proof_types` relationship to determine which Proof
  Types are accepted.
- `external_reference_id` is optional and has a maximum length of 100 characters.
- Once approved, an Address may be reused for DID types with the same level of restrictions,
  provided that it continues to satisfy the applicable Address Requirement.

## Endpoints

| Action | Method | Endpoint |
| --- | --- | --- |
| Retrieve all Addresses | `GET` | `/v3/addresses` |
| Retrieve Address | `GET` | `/v3/addresses/{id}` |
| Create Address | `POST` | `/v3/addresses` |
| Update Address | `PATCH` | `/v3/addresses/{id}` |
| Delete Address | `DELETE` | `/v3/addresses/{id}` |

## Retrieve all Addresses

Retrieves all Addresses associated with the account.

Use this endpoint to find an existing Address before creating another one. Results can be
filtered by city name, postal code, full address, description, external reference ID, or
related Identity, country, Area, and City IDs. Related Identity, country, Proof, Area, and
City records can be included in the response.

See [Retrieve All Addresses](get-addresses.html).

```
GET /v3/addresses
```

## Retrieve Address

Retrieves a specific Address by its unique ID.

Use this endpoint to inspect the Address attributes, `verified` status, and related
Identity, country, Proofs, Area, or City. Related Identity proofs and permanent documents can
also be included when reviewing registration readiness.

See [Retrieve Address](get-address.html).

```
GET /v3/addresses/{id}
```

## Create Address

Creates an Address associated with an Identity and country.

Use the applicable Address Requirement to select a compliant location. Provide the city
name, postal code, and full address, then link the Address to the Identity that represents
the end user.

See [Create Address](create-address.html).

```
POST /v3/addresses
```

## Update Address

Updates an existing Address by its unique ID.

Use this endpoint to modify the city name, postal code, full address, description, or
external reference ID.

See [Update Address](update-address.html).

```
PATCH /v3/addresses/{id}
```

## Delete Address

Permanently deletes an Address by its unique ID. A deleted Address cannot be restored.

See [Delete Address](delete-address.html).

```
DELETE /v3/addresses/{id}
```

## Data reference

See [Address Object](address-object.html) for all attributes and relationships returned by
the resource.

## Common Address use cases

| Use case | Description |
| --- | --- |
| Find a reusable Address | Search existing records by Identity, country, Area, City, or address details before creating a duplicate. |
| Create an address for an Identity | Store the physical location required for an end-user registration and link it to the appropriate Identity. |
| Meet geographic restrictions | Use the requirement country, Area, or City to provide an Address that satisfies `address_area_level`. |
| Add address proofs | Link accepted Proofs when the Address Requirement requires evidence of the physical location. |
| Review verification readiness | Retrieve the Address with its Identity, Proofs, and location relationships before validating the registration data. |
| Reconcile external records | Store and filter by `external_reference_id` to associate the Address with a record in another system. |
| Correct address information | Update address attributes before creating an Address Requirement Validation or Address Verification. |

## Related resources

- [Address Requirements](../requirements/index.html) - Determine the permitted address
  location and required Proof Types.
- [Identities](../identities/index.html) - Retrieve or create the Identity linked to the
  Address.
- [Areas](../areas/index.html) - Retrieve regulatory Areas used for area-level location
  restrictions.
- [Proofs](../proofs/index.html) - Link accepted evidence to the Address.
- [Address Requirement Validation](../requirements/address-requirement-validations.html) - Check the Identity and Address
  against the selected requirement.
- [Address Verifications](../address-verifications/index.html) - Submit DIDs and the
  prepared Address for review.
- [Countries](../../coverage-resources/countries/index.html) - Retrieve country IDs for
  the Address relationship.
- [Cities](../../coverage-resources/city/index.html) - Retrieve City records used by
  city-level address requirements.

On this page