Skip to main content
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.
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.

​
Address fields

FieldRequiredDescription
street_addressYesStreet number and name
apartmentNoUnit, apartment, suite, or level
cityYesCity or suburb
stateNoState or province
countryYesCountry (ISO 3166-1 alpha-2 code recommended)
postcodeYesPostcode or ZIP code
nameNoFriendly label for the address (e.g., My Home, Office)
typeNoAddress type (e.g., Home, Work)
phoneNoContact phone number for this address, including country code
companyNoCompany or organisation name associated with this address
notesNoFree-text delivery instructions or notes
metaNoArbitrary JSON metadata for integration or brand-specific use
is_defaultBooleanWhether this is the profile’s primary address
external_idNoExternal 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
The Profile Addresses API supports browse, create, read, update, delete, and upsert-by-external-id operations. See the Addresses API for full endpoint reference.

​
Mutation semantics on the main Profile endpoints

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 instead. See Mutation semantics on POST and PUT for the equivalent behaviour on other profile collections.