HLTH 2026Vorro is at HLTH 2026, Las Vegas, Nov 15–18. Bring your toughest interoperability problem.Book a meeting
HL7 v2Data Type⏱ 8 min read

HL7 XAD Data Type: Extended Address

In short

The XAD data type carries a structured postal address with street, city, state, postal code, type, and validity period in PID-11; it maps to the FHIR Address.

Need this HL7 v2 feed built or fixed?Contact Us

The XAD (Extended Address) data type was introduced in HL7 v2.3 to replace the older flat AD type. It carries a fully structured postal address - street (itself a composite SAD), other designation (apt/suite/unit), city, state or province, postal code, country, address type, and an effective/expiration period so historical addresses can travel alongside the current one. Its flagship fields are PID-11 Patient Address and NK1-4 Next of Kin Address.

Purpose

XAD exists so a postal address can be exchanged with components that downstream systems can validate, map, and re-render. A single patient may have several addresses simultaneously - home, billing, temporary, prior - and XAD encodes each one with an explicit address type code and effective/expiration dates so consumers can filter by current vs. historical addresses without guessing. The structured Street Address sub-type (SAD) further decomposes the street line so dwelling number, street name, and street type can be exchanged separately when a profile requires it.

Component table

Source: HAPI HL7v2 v2.8.1 javadocs (XAD). Lengths are no longer published as fixed maxima in v2.8.1 (-); Required and Table # are taken from the HL7 v2 standard where well-established. XAD has 14 components in v2.7+.

CompNameSub-typeLengthRequiredDescription
XAD.1Street Addresssad-OStructured street line (street, dwelling, street name).
XAD.2Other Designationst-OApt / suite / unit / building / floor.
XAD.3Cityst-OCity or locality.
XAD.4State or Provincest-OState, province, or sub-national region (USPS 2-letter for US).
XAD.5Zip or Postal Codest-OZIP or postal code, country-specific format.
XAD.6Countryid-O[HL70399] ISO 3166-1 alpha-3 country code (e.g. USA).
XAD.7Address Typeid-O[HL70190] H home, M mailing, B billing, O office, BA bad address, BI birth, etc.
XAD.8Other Geographic Designationst-ORegion, district, locality not fitting state/city.
XAD.9County/Parish Codecwe-O[HL70289] FIPS or county code. CWE since v2.5.
XAD.10Census Tractcwe-OCensus tract code for the address.
XAD.11Address Representation Codeid-O[HL70465] Alphabetic, ideographic, phonetic.
XAD.12Address Validity Rangedr-WWithdrawn in v2.5. Use XAD.13 / XAD.14 instead.
XAD.13Effective Datedtm-ODate the address became valid. Added v2.5.
XAD.14Expiration Datedtm-ODate the address stopped being valid. Added v2.5.

Most-used components

  • XAD.1 Street Address - the primary street line, itself a SAD composite.
  • XAD.3 City - locality.
  • XAD.4 State or Province - USPS 2-letter for US senders; free text in other locales.
  • XAD.5 Zip or Postal Code - ZIP+4 or country-specific postal code.
  • XAD.6 Country - ISO 3166-1 alpha-3 from HL70399 (e.g. USA, CAN, GBR).
  • XAD.7 Address Type (HL70190) - H home, M mailing, B billing, O office, BA bad address, BI birth, C current/temporary, P permanent.

Where it's used

XAD is the canonical postal-address carrier across the v2 standard. The most common occurrences:

  • PID-11 Patient Address - repeating; home address first, then mailing / billing / prior.
  • PID-12 County Code - though typically a separate IS field, the county is often duplicated into XAD.9.
  • NK1-4 Next of Kin Address - repeating.
  • GT1-5 Guarantor Address.
  • IN1-19 Insured's Address and IN2-37 Mother's Address.
  • ORC-23 Ordering Facility Address and ORC-24 Ordering Provider Address.
  • PV1-23 Billing Address (when present in profiles that carry it).
  • STF-11 Staff Address (master-file staff record).
  • DON-18 Intended Recipient Facility (embedded address fields).

Version differences

  • v2.3 - XAD introduced with components .1 through .8, replacing the flat AD type.
  • v2.4 - Component .9 County/Parish Code added as IS; .10 Census Tract added; .11 Address Representation Code added.
  • v2.5 - XAD.9 County/Parish Code promoted from IS to CWE. XAD.12 Address Validity Range (DR) withdrawn; XAD.13 Effective Date and XAD.14 Expiration Date added as DTM. XAD.10 Census Tract promoted to CWE.
  • v2.6 - XAD.1 Street Address became the structured SAD composite.
  • v2.7 / v2.8 / v2.8.1 - No further structural changes; v2.8.1 retains the 14-component layout documented above. HL70399 country list updated to ISO 3166-1 alpha-3.

Common mistakes

  • Cramming the entire street into XAD.1 ambiguously. "123 Main St Apt 4B" should split: 123 Main St in XAD.1, Apt 4B in XAD.2 Other Designation. Receivers that match on street line will fail to deduplicate.
  • Local country abbreviations instead of ISO 3166 alpha-3. Sending US or United States in XAD.6 breaks downstream systems expecting HL70399 (USA).
  • Free-text state names. US profiles expect the USPS 2-letter abbreviation in XAD.4. "California" instead of CA defeats automated geocoding.
  • Omitting XAD.7 Address Type. Without H / M / B, repeating PID-11 addresses are indistinguishable; consumers cannot tell home from billing.
  • Populating the withdrawn XAD.12 Validity Range on v2.5+ messages. Use XAD.13 / XAD.14 DTM pair instead.
  • Mixing structured SAD and free-text in XAD.1. Either commit to SAD sub-components (123&Main&St) or use the unstructured form (123 Main St); mixing them confuses receivers.
  • ZIP+4 sent without the hyphen in XAD.5. US ZIP+4 is conventionally 94105-1234; bare 941051234 is technically legal but commonly rejected by US payer scrubbers.

Examples

Minimal value

123 Main St^^Anytown^CA^94000

Multi-component populated with all seven primary components

123 Main St^Apt 4B^Anytown^CA^94105-1234^USA^H

123 Main St street, Apt 4B other designation, Anytown city, CA state, 94105-1234 ZIP+4, USA country, H home address type.

Fully populated edge case with county CWE, effective dates, and structured SAD

123&Main&St^Apt 4B^Anytown^CA^94105-1234^USA^H^^06075^Census-1234.00^A^^20200101^

Structured SAD (123 dwelling, Main street name, St street type), county 06075 (San Francisco FIPS), census tract 1234.00, alphabetic representation, effective 2020-01-01, no expiration.

Multiple addresses as XAD repetitions (home + billing)

123 Main St^Apt 4B^Anytown^CA^94105-1234^USA^H~PO Box 9000^^Anytown^CA^94109^USA^M

In-context excerpt - PID-11 with home + mailing

PID|1||MR884412^^^MERCY^MR||Smith^John^Q||19720508|F|||123 Main St^Apt 4B^Anytown^CA^94105-1234^USA^H~PO Box 9000^^Anytown^CA^94109^USA^M

Common pitfall - country and state mis-coded

PID|1||MR884412^^^MERCY^MR||Smith^John^Q||19720508|F|||123 Main St^^Anytown^California^94105^US^H

California should be CA; US should be USA per HL70399. Both errors fail HL7 v2.8.1 conformance and downstream geocoding.

FHIR mapping

The v2-to-FHIR Implementation Guide publishes a ConceptMap from XAD to FHIR Address.

XAD componentFHIR element
XAD.1 Street Address (SAD) + XAD.2 Other DesignationAddress.line (multiple entries, one per line)
XAD.3 CityAddress.city
XAD.4 State or ProvinceAddress.state
XAD.5 Zip or Postal CodeAddress.postalCode
XAD.6 CountryAddress.country
XAD.7 Address TypeAddress.use (home/work/temp/old) and Address.type (postal/physical/both)
XAD.9 County/Parish CodeAddress.district
XAD.13 Effective DateAddress.period.start
XAD.14 Expiration DateAddress.period.end

Engine considerations

  • Repetition order matters. PID-11 carries the primary home address first; mailing/billing/prior follow. Engines that re-sort repetitions silently change which address is "primary".
  • SAD sub-component handling. XAD.1 is itself a composite (street & dwelling & numeric & ...). Engines that flatten XAD.1 to a single string lose the dwelling-number / street-name / street-type structure. Preserve &-delimited sub-components verbatim.
  • HAPI accessor. HAPI v2.8.1 exposes XAD as ca.uhn.hl7v2.model.v281.datatype.XAD with typed getters (getStreetAddress(), getCity(), getAddressType()); PID-11 repetitions are accessed through Pid.getPatientAddress() which returns XAD[].
  • Country code value-set. HL70399 specifies ISO 3166-1 alpha-3. Engines bridging from FHIR (which uses alpha-2 by convention) must translate.
  • County (XAD.9) is CWE since v2.5. Engines parsing pre-v2.5 messages must treat XAD.9 as IS; v2.5+ requires CWE structure.

How Vorro parses and produces XAD

Vorro's HL7 parser deserializes every XAD into a typed PostalAddress object that preserves the SAD sub-structure of XAD.1 (dwelling, street name, street type) and the full set of XAD.2–XAD.14 components. XAD.6 Country is normalized against HL70399 / ISO 3166-1 alpha-3; XAD.7 Address Type is normalized against HL70190 with missing values tagged "unspecified" rather than silently defaulted to home. PID-11 repetitions are preserved in their inbound order so the home-first convention round-trips.

On outbound, Vorro emits the home address as the first XAD repetition and any mailing / billing / prior variants as subsequent repetitions, each with an explicit XAD.7 code. Country is always emitted as ISO 3166-1 alpha-3, state as USPS 2-letter for US addresses, and lifecycle dates use XAD.13 / XAD.14 rather than the withdrawn XAD.12 Validity Range.

Sources

← Back to HL7 v2 Guide

Ready to Integrate This Into Your Workflow?

Talk to a Vorro expert about implementing HL7 v2 in your specific environment.