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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.