> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omneo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Addresses

> How Omneo stores and manages customer address records linked to profiles.

**Addresses** in Omneo are postal locations associated with a profile. A profile can have one or more addresses representing a customer's home, workplace, delivery address, or any other location relevant to the brand.

<Warning>
  Addresses are for complete postal locations. Do not use an address record to store partial location data such as a suburb, postcode, or country alone. For geographic segmentation at that level, assign a Region (which supports down to state level) or store a postcode as a custom attribute.
</Warning>

## Address fields

| Field            | Required | Description                                                   |
| ---------------- | -------- | ------------------------------------------------------------- |
| `street_address` | Yes      | Street number and name                                        |
| `apartment`      | No       | Unit, apartment, suite, or level                              |
| `city`           | Yes      | City or suburb                                                |
| `state`          | No       | State or province                                             |
| `country`        | Yes      | Country (ISO 3166-1 alpha-2 code recommended)                 |
| `postcode`       | Yes      | Postcode or ZIP code                                          |
| `name`           | No       | Friendly label for the address (e.g., `My Home`, `Office`)    |
| `type`           | No       | Address type (e.g., `Home`, `Work`)                           |
| `phone`          | No       | Contact phone number for this address, including country code |
| `company`        | No       | Company or organisation name associated with this address     |
| `notes`          | No       | Free-text delivery instructions or notes                      |
| `meta`           | No       | Arbitrary JSON metadata for integration or brand-specific use |
| `is_default`     | Boolean  | Whether this is the profile's primary address                 |
| `external_id`    | No       | External reference ID for upsert operations                   |

## Default address

A profile can have only one default address at a time. The default address is returned on the main profile response. All other addresses are returned via the profile addresses endpoint.

To change the default address, update the desired address with `is_default: true`.

## Use cases

Addresses are used to power:

* **Click and collect:** delivery to the customer's preferred location
* **Postal communications:** physical mail and direct mail campaigns
* **Address-based personalisation:** surfacing local store information based on proximity
* **eReceipts:** including the billing address on digital receipts

<Info>
  The Profile Addresses API supports browse, create, read, update, delete, and upsert-by-external-id operations. See the [Addresses API](/api-reference/profile-address) for full endpoint reference.
</Info>

## Mutation semantics on the main Profile endpoints

<Warning>
  Including the `addresses` array on `POST /v3/profiles` or `PUT /v3/profiles/{profile}` is a **destructive replace**, not a merge.

  * Omitting the `addresses` key from the request body leaves existing addresses untouched.
  * Sending `addresses: []` soft-deletes every existing address on the profile.
  * Sending `addresses: [partial list]` soft-deletes every existing address, then recreates from the supplied list. Anything not in the supplied array is destroyed.

  For add, update, or delete of a single address, use the [Profile Addresses API](/api-reference/profile-address/overview) instead. See [Mutation semantics on POST and PUT](/concepts/profiles/overview#mutation-semantics-on-post-and-put) for the equivalent behaviour on other profile collections.
</Warning>

## Related

* [Profiles](/concepts/profiles/overview)
* [Localisation](/concepts/profiles/localisation)
* [Addresses API](/api-reference/profile-address)