Store an address without throwing away the unit number

Give each address a purpose and version

Create an address record with its own identity, role and revision. Link customers, sites or jobs to that record according to the business model. Avoid treating a formatted label as the only source of truth.

Keep the country and postcode as strings. Use text for unit and street-number components where the model supports them. A display formatter can then produce an appropriate label without forcing every integration to parse free text.

This synthetic record illustrates provenance and purpose. Its components are demonstration values, not a deliverable real address.

{
  "addressId": "address-example-12",
  "role": "serviceLocation",
  "revision": 3,
  "unit": "2B",
  "streetNumber": "18",
  "streetName": "Example",
  "streetType": "Road",
  "locality": "Example Town",
  "postcode": "0800",
  "country": "AU",
  "matchState": "manualReview"
}

Treat autocomplete as an editable suggestion

After selection, show the complete proposed address and allow correction. If a component that determines the match changes, invalidate the old match metadata and recheck as needed.

Provide manual entry from the beginning. An unavailable lookup service should not make the entire form unusable unless the transaction genuinely requires a verified match before proceeding.

Keep delivery instructions separate from address components. A gate code placed in a street field can leak into labels, analytics and unrelated downstream systems.

Validate at the relevant boundary

Check required fields against the chosen address purpose. A service visit normally needs a physical destination, while a postal contact may legitimately use a PO Box. Carrier-specific restrictions belong in the shipping integration's validation.

Do not silently truncate components to fit a downstream field. Return an actionable error or use the provider's supported multi-line representation. A truncated unit or building name can change the destination.

Preserve historical destinations

When creating a job or shipment, record the address revision or an appropriate snapshot used for that action. A later profile edit should not rewrite the evidence of where an earlier item was sent.

Test the round trip through forms, exports and integrations. The unit, leading postcode zero and manual-review state should survive, not merely look correct on the first screen.