HL7 VXX Messages: Vaccination Query Response — Multiple Patient Match

HL7 VXX messages are sent by an immunization registry when a vaccination query matches more than one patient. A VXX message does not return vaccination records — it returns a list of candidate patient demographics so the querying system can identify the correct patient and resubmit the query with a definitive identifier. This page explains what a VXX message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a VXX candidate list relates to FHIR. Sample content is constructed for illustration with fictional identifiers.

What a VXX message represents

A VXX message — VXX stands for Response to Vaccination Query — Multiple Patient Match — is the registry's reply to a VXQ^V01 vaccination query when the supplied patient identifier or demographic criteria match more than one patient in the registry. Instead of returning an immunization history, the registry returns the minimal patient demographics it needs to expose so the requesting system can distinguish one candidate from another: name, date of birth, sex, address, and the identifier list from each matching patient's PID segment.

The sender is the immunization information system (IIS) or registry that holds the patient population; the receiver is the clinical or public-health application that sent the original VXQ. A VXX message is always paired with a prior VXQ^V01: the registry sends it only when the query could not be resolved to a single unique patient. The querying system is expected to present the candidates to a user or apply its own probabilistic logic, select one, and resubmit the query carrying the registry-assigned identifier that uniquely identifies the chosen patient — which then yields a VXR^V03 with the actual immunization history.

VXX is deliberately narrow in scope. Unlike VXR, which returns a full ORDER group per vaccination event, VXX carries no clinical data whatsoever — no vaccine codes, no lot numbers, no administration dates. Each repeating PATIENT group contains only a PID and optional NK1 segments, providing just enough demographic information to disambiguate. This keeps the response compact and avoids transmitting immunization records for patients the requester did not intend to query.

When a VXX message is sent

A VXX message is sent when a registry or IIS receives a VXQ^V01 vaccination query and the matching logic finds two or more patients whose identifier or demographics satisfy the query criteria. Common scenarios include a query that supplies only a medical record number not registered at the IIS, a query with common demographic values (a frequent name and a rounded date of birth), or probabilistic matching that produces several candidates above the registry's confidence threshold.

Trigger event

The VXX message type carries a single trigger event:

• VXX^V02 – Response to vaccination query with multiple patient matches.

The trigger code V02 distinguishes this response from VXR^V03 (single patient match, vaccination history returned) and from a no-data acknowledgement. Receivers must handle VXX^V02 as a distinct outcome — not as an error — and route the candidate list through a disambiguation workflow before the query can be resolved.

Integration topology

The diagram shows the querying clinical system sending a VXQ, the registry finding multiple matches, and the VXX candidate list returning to the requester for disambiguation before a resolved requery produces a VXR.

{{diagram: clinical system → VXQ^V01 query → immunization registry (multiple matches) → VXX^V02 candidate list → clinical system (disambiguation) → VXQ^V01 requery with definitive identifier → immunization registry → VXR^V03 vaccination history → clinical system}}

Typical senders: immunization information system (IIS), state or regional immunization registry, public-health authority.

Typical receivers: EHR, point-of-care immunization application, public-health reporting client, school or occupational health system.

Direction: point-to-point response from the registry to the requesting system, always paired with an originating VXQ query; resolution requires a subsequent VXQ requery.

Segments in a VXX message

The VXX_V02 message is organised into a fixed header block — MSH, MSA, optional errors, query metadata — followed by one or more repeating PATIENT groups, each carrying the demographics of a single candidate patient. Cardinality follows HL7 notation: [X] optional, {X} repeating, [{X}] optional and repeating; a bare code is required. Each segment code links to its canonical field-by-field reference.

[ ] = optional, { } = repeating

The PATIENT group from PID through NK1 repeats once per candidate patient returned by the registry, so a single VXX message delivers the full list of matches. The canonical segment pages carry the full field-by-field detail.

Sample VXX message

Note. Constructed for illustration. Patient identifiers, query identifiers, dates, and names are fictional.

MSH|^~&|IMMREG|STATEIIS|EHR|MERCYCLINIC|20260604094500||VXX^V02^VXX_V02|MSG00098|P|2.5.1
MSA|AA|QRY20260604001
QAK|QRY20260604001|TM|Z34^Request Immunization History^CDCPHINVS
QRD|20260604093000|R|I|QRY20260604001|||999^RD|PT789456^^^GREENVALLEY^MR|VXQ|IMM
PID|1||SR100234^^^STATEIIS^SR~PT789456^^^GREENVALLEY^MR||SMITH^JOHN^A||19750312|M|||456 ELM ST^^SPRINGFIELD^IL^62702
PID|2||SR200891^^^STATEIIS^SR~PT789456^^^GREENVALLEY^MR||SMITH^JOHN^B||19750312|M|||789 OAK AVE^^SPRINGFIELD^IL^62703
NK1|1|SMITH^MARY^J|SPO^Spouse^HL70063

What this sample shows

The VXX^V02 in MSH-9 marks a multiple patient match response. MSA carries AA confirming the query was accepted and echoes the originating query control id QRY20260604001 in MSA-2. QAK carries status TM — too many matches — signalling to the receiver that no vaccination records follow and disambiguation is required. QRD echoes the query parameters including the patient identifier PT789456 that produced the ambiguous result.

The first PID carries candidate one: registry identifier SR100234, also cross-referenced to the sending system's PT789456, name JOHN A SMITH, date of birth 19750312, sex M, and address 456 ELM ST. The second PID carries candidate two: a different registry identifier SR200891, the same cross-reference, name JOHN B SMITH, matching date of birth and sex, but a different address 789 OAK AVE. The NK1 following the second PID identifies the spouse MARY J SMITH. The requester must present these two candidates to a user or resolve them programmatically, then resubmit the query with the confirmed registry identifier — SR100234 or SR200891 — to receive the correct patient's vaccination history in a VXR^V03.

Working with VXX messages

VXX is an intermediate state, not a final answer

A VXX response means the query is unresolved. The receiving system must not record a no-data outcome, discard the response, or apply any immunization history to the patient — instead it must route the candidate list through a disambiguation step. Design query workflows with an explicit VXX state: hold the originating query pending, surface the candidates, and trigger a requery once a selection is made.

Use PID-3 from the selected candidate as the requery identifier

Each candidate PID carries the registry's own identifier in PID-3. When the requester selects a candidate, it must resubmit the VXQ carrying that registry-assigned identifier — not the original sending-system identifier that produced the ambiguous match — in QRD-8. Using the registry's own identifier guarantees the requery resolves to exactly one patient and returns a VXR^V03 with the correct vaccination history.

Correlate the response to its originating query

MSA-2 echoes the message control id of the originating VXQ, and QAK-1 carries the query tag. Both must be matched back to the pending query before the candidate list is processed. A VXX that cannot be correlated to an outstanding query should be held for review, since the absence of a matching query means the patient context cannot be confirmed and presenting the wrong candidates could lead to a mis-routed requery.

Check QAK-2 for the match status code

QAK-2 in a VXX response is typically TM (too many matches) but some registries return OK when they choose to return all candidates without signalling an overflow. Confirm the expected value with each registry's interface specification, and treat both TM and OK with multiple following PATIENT groups as a disambiguation-required outcome rather than as a successful single-patient response.

Vendor variance. Registries differ in how many candidates they return in a VXX — some cap the list at five or ten candidates and truncate, others return all matches up to a system limit. Some emit an ERR segment noting the truncation; others do not. Confirm candidate-list limits against the registry's interface specification or the relevant CDC HL7 2.5.1 immunization implementation guide profile.

FHIR equivalent

A VXX candidate list corresponds conceptually to a FHIR searchset Bundle of Patient resources — the registry returns one Patient resource per candidate, and the requester uses the Patient identifiers to select the correct record before querying for Immunization resources.

There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for VXX_V02. The closest published map is for VXU_V04 (the unsolicited vaccination record update), which maps to a Bundle containing MessageHeader, Patient, and Immunization resources. Because VXX carries only patient demographics and no clinical payload, it has no direct FHIR message equivalent; the conceptual correspondence is to a FHIR Patient?identifier=<system>|<value> search response typed as a searchset. Systems migrating from VXQ/VXX-based IIS query flows to FHIR should target the Patient search and Immunization search APIs defined by the relevant FHIR implementation guide for their jurisdiction.

Common pitfalls

Pitfall. Treating VXX as an error rather than a query workflow state. A VXX response is a valid, expected outcome — not a failure. Systems that log VXX as an error and discard the response will silently stall the query workflow, leaving the user without vaccination history and with no visible indication that disambiguation is needed.

Pitfall. Requerying with the original identifier after receiving a VXX. Resubmitting the same VXQ with the same identifier will produce another VXX. The requery must carry the registry-assigned identifier from the selected candidate's PID-3 — the identifier that is unique within the registry — to resolve to a single patient match.

Pitfall. Applying NK1 data from one candidate to another. Each NK1 segment in a VXX response belongs to the PID immediately preceding it in the same PATIENT group. Misassigning a next-of-kin record to the wrong candidate can corrupt the disambiguation display and mislead the user into selecting the incorrect patient.

How Vorro handles VXX messages

Vorro receives VXX responses over MLLP, correlates each response to its originating VXQ query using MSA-2 and QAK-1, and routes the candidate patient list through a configurable disambiguation workflow. Vorro reads each PATIENT group, extracts the registry identifier, name, date of birth, sex, and address from each PID, and surfaces the candidates to the requesting application. When the user or downstream logic selects a candidate, Vorro automatically constructs and dispatches the requery VXQ^V01 carrying the registry's own identifier from PID-3, so the resolved query can return a VXR^V03 with the correct patient's vaccination history. Where a FHIR destination is configured, Vorro maps each candidate PID to a FHIR Patient resource — composed manually, since the v2-to-FHIR Implementation Guide publishes no message map for VXX_V02.

Related messages

• VXQ — the vaccination query that a VXX message responds to when more than one patient matches the query criteria.
• VXR — the registry's response when a VXQ query resolves to exactly one patient; carries the complete vaccination history.
• VXU — the unsolicited vaccination record update that reports a newly administered immunization to the registry without a preceding query.

Sources

• HL7 v2-to-FHIR IG — message maps index — confirms no message map for VXX_V02
• HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for QAK or QRD in a VXX context
• HL7 Messaging Standard Version 2.5.1 product brief