HL7 XTN Data Type: Extended Telecommunication Number

The XTN (Extended Telecommunication Number) data type was introduced in HL7 v2.3 to replace the older flat TN type. It carries any kind of telecommunication endpoint — voice phone, fax, pager, beeper, modem, internet email, or URI — along with a use code (home, business, emergency), an equipment type (phone, fax, internet), structured country/area/local/extension digits, an unformatted display form, and a validity period. Its flagship fields are PID-13 Phone Number — Home and PID-14 Phone Number — Business.

Purpose

XTN exists so that any contact endpoint — not just a voice phone — can be exchanged with enough structure to be machine-routed. The same XTN can carry a North American phone (555-555-1234), an international phone (+44 20 7946 0958), a fax, a pager, an SMS number, an email address (jane@example.com), or a generic URI (tel:+15555551234, sip:jane@pbx.example.com). The use code and equipment type let downstream systems filter "send me only mobile numbers" or "send me only email addresses" without guessing from the digits.

Component table

Source: HAPI HL7v2 v2.8.1 javadocs (XTN). 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. XTN has 18 components in v2.7+.

Most-used components

• XTN.2 Telecommunication Use Code (HL70201) — PRN primary home, WPN work, ORN other, NET network/email, EMR emergency.
• XTN.3 Telecommunication Equipment Type (HL70202) — PH phone, FX fax, CP cellular, Internet email, BP beeper.
• XTN.4 Communication Address — the email address (jane@example.com) or URI when XTN.3 is Internet.
• XTN.6 / XTN.7 / XTN.8 — area code, local number, extension as separate NM digits for structured routing.
• XTN.12 Unformatted Telephone Number — the modern preferred field for the full human-readable number; the FHIR mapping reads from here.
• XTN.18 Preference Order — when a patient has several numbers, this NM ranks them so receivers know which to try first.

Where it's used

XTN is the canonical contact-endpoint carrier across the v2 standard. The most common occurrences:

• PID-13 Phone Number — Home — repeating; home voice, mobile, email all carried as XTN repetitions.
• PID-14 Phone Number — Business — repeating.
• PID-40 Patient Telecommunication Information — added v2.7 as a richer alternative.
• NK1-5 Phone Number and NK1-6 Business Phone Number.
• STF-10 Phone (master-file staff phone).
• GT1-6 Guarantor Phone Number — Home and GT1-7 Phone — Business.
• IN1-7 Insurance Company Phone Number.
• OBR-17 Order Callback Phone Number — clinician callback for results.
• PRT-15 Participation Phone — participation-segment phone.
• MSH-22 / MSH-24 sending/receiving network address (in profiles that carry XTN here).

Version differences

• v2.3 — XTN introduced with components .1 through .9, replacing the flat TN type. XTN.1 carried the formatted (area) local-ext string.
• v2.4 — Components .10 Extension Prefix and .11 Speed Dial Code added.
• v2.5 — Major rework. Components .12 Unformatted Telephone Number, .13 Effective Date, .14 Expiration Date added. XTN.5–XTN.8 became the structured numeric form. Implementations encouraged to migrate from XTN.1 to XTN.12 / XTN.5–8.
• v2.6 — Components .15 Expiration Reason, .16 Protection Code, .17 Shared Telecommunication Identifier added.
• v2.7 — XTN.1 Telephone Number formally withdrawn; senders should use XTN.12 (or the XTN.5–XTN.8 structured form). Component .18 Preference Order added.
• v2.8 / v2.8.1 — No further structural changes. The v2.8.1 javadoc confirms the 18-component layout documented above.

Common mistakes

• Filling the withdrawn XTN.1 instead of XTN.12. Legacy bridges still emit (555)555-1234^PRN^PH with the number in XTN.1. On v2.7+ this is non-conformant; the human-readable form belongs in XTN.12.
• Mixing XTN.4 email content with XTN.5–XTN.8 phone digits. An XTN that carries an email address (XTN.3 = Internet, value in XTN.4) must leave the numeric components empty. Putting 555 in XTN.6 of an email row corrupts FHIR mapping.
• Sending phone country code with + prefix in XTN.5. XTN.5 is NM (numeric) — 1, not +1. The + lives only in the formatted XTN.12 (+1 555-555-1234).
• Omitting XTN.2 Use Code. Without PRN / WPN / NET, downstream consumers cannot distinguish home from work from email and may dial the wrong number.
• Omitting XTN.3 Equipment Type. Without PH / CP / Internet, consumers cannot tell whether to text, call, or email.
• Sending a single repetition that mixes home phone and email. Each endpoint must be its own XTN repetition separated by ~, not crammed into one XTN.
• Using HL70201 codes in XTN.3 (Equipment) or HL70202 codes in XTN.2 (Use). The two tables are easy to swap; receivers reject mis-coded values.

Examples

Minimal value (US home phone)

^PRN^PH^^^555^5551234

PRN use, PH equipment, area 555, local 5551234. No country code, no extension, XTN.1 left empty.

Multi-component populated with country, area, local, extension

^WPN^PH^^1^415^5551234^42^^^^+1 415-555-1234 x42

WPN work, PH phone, country 1, area 415, local 5551234, extension 42, formatted in XTN.12.

Email as an XTN (Communication Address in XTN.4)

^NET^Internet^john@example.com

NET network use, Internet equipment type, address john@example.com in XTN.4. Numeric components left empty.

Fully populated edge case with preference order, effective date, protection

^PRN^CP^^1^415^5551234^^Ask for Maria^^^+1 415-555-1234^20200101^^^UNLST^^1

PRN cellular, country 1 area 415 local 5551234, free-text "Ask for Maria", unformatted +1 415-555-1234, effective 2020-01-01, protection UNLST (unlisted), preference order 1 (primary).

In-context excerpt — PID-13 with phone + email repetitions

PID|1||MR884412^^^MERCY^MR||Smith^John^Q||19720508|F|||123 Main St^^Anytown^CA^94000^USA^H||^PRN^PH^^^555^5551234~^NET^Internet^john@example.com|^WPN^PH^^1^415^5559999^42

PID-13 carries the home phone and email as two XTN repetitions separated by ~; PID-14 carries the work phone with extension.

Common pitfall — + prefix in numeric XTN.5

^WPN^PH^^+1^415^5551234^42

XTN.5 is NM; +1 is non-numeric and most strict parsers will reject the message. Use 1 in XTN.5 and put the + only inside the formatted XTN.12 string.

FHIR mapping

The v2-to-FHIR Implementation Guide publishes a ConceptMap from XTN to FHIR ContactPoint.

• ConceptMap: datatype-xtn-to-contactpoint

Engine considerations

• Repetition order matters. PID-13 carries the primary home contact first; engines should not re-sort repetitions because XTN.18 Preference Order is optional and many senders rely on positional ordering instead.
• Prefer XTN.12 on outbound for FHIR compatibility. The v2-to-FHIR ConceptMap reads ContactPoint.value from XTN.12; engines that only populate XTN.1 will produce empty FHIR ContactPoints when bridged.
• Equipment vs. use confusion. HL70201 (use) and HL70202 (equipment) share short two- to three-letter codes and are easy to swap. Validate against the correct table for each component.
• Email vs. phone discriminator. When XTN.3 = Internet, the value lives in XTN.4 and XTN.5–XTN.8 must be empty. Engines bridging to FHIR should branch on XTN.3 to choose ContactPoint.system.
• HAPI accessor. HAPI v2.8.1 exposes XTN as ca.uhn.hl7v2.model.v281.datatype.XTN with typed getters (getTelecommunicationUseCode(), getCommunicationAddress(), getUnformattedTelephoneNumber()); PID-13 repetitions are accessed through Pid.getPhoneNumberHome() which returns XTN[].
• Numeric vs. string components. XTN.5–XTN.8 and XTN.18 are NM. Engines that emit non-digit characters (+, -, spaces) here will fail strict conformance.

How Vorro parses and produces XTN

Vorro's HL7 parser deserializes every XTN into a typed ContactEndpoint object that captures use code, equipment type, structured digits, communication address, and the unformatted form. Inbound XTN.1 (legacy, withdrawn) is read for backward compatibility but mirrored into XTN.12 internally so all downstream consumers see a single canonical "value" field. PID-13 repetitions are preserved in their inbound order; XTN.18 Preference Order, when present, overrides ordering for the typed model but the wire-level repetition order is round-tripped intact.

On outbound, Vorro always populates XTN.12 with the formatted human-readable form and also fills XTN.5–XTN.8 with the structured numeric digits (no + prefix in XTN.5). Email and URI endpoints are emitted as separate XTN repetitions with XTN.3 = Internet and the address in XTN.4. XTN.1 is left empty per v2.7+ guidance. Lifecycle dates use XTN.13 / XTN.14, and a ContactPoint.rank originating from FHIR is translated back into XTN.18.

Related pages

• XPN data type — Extended Person Name
• XAD data type — Extended Address
• PID segment — Patient Identification
• NK1 segment — Next of Kin

Sources

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