HL7 XAD Data Type: Extended Address

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+.

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.

• ConceptMap: datatype-xad-to-address

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.

Related pages

• XPN data type — Extended Person Name
• XTN data type — Extended Telecommunication Number
• SAD data type — Street Address
• PID segment — Patient Identification
• NK1 segment — Next of Kin

Sources

• HAPI HL7v2 v2.8.1 javadoc — XAD data type
• HAPI HL7v2 v2.8.1 apidocs index
• HL7 v2 product brief
• v2-to-FHIR ConceptMap: XAD → Address