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

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

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.

PATCH /v3/addresses/{id}

Delete Address

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

See Delete Address.

DELETE /v3/addresses/{id}

Data reference

See Address Object 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 — Determine the permitted address location and required Proof Types.

• Identities — Retrieve or create the Identity linked to the Address.

• Areas — Retrieve regulatory Areas used for area-level location restrictions.

• Proofs — Link accepted evidence to the Address.

• Address Requirement Validation — Check the Identity and Address against the selected requirement.

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

• Countries — Retrieve country IDs for the Address relationship.

• Cities — Retrieve City records used by city-level address requirements.