HL7 VXQ messages query an immunization registry or clinical system for a patient's vaccination history. A VXQ message asks: given this patient identifier — and, optionally, demographic filter criteria — return all vaccination records on file. The registry responds with a VXR message when it finds exactly one matching patient, or a VXX message when the query matches multiple patients and the requester must disambiguate. This page explains what a VXQ message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a VXQ query relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
What a VXQ message represents
A VXQ message — VXQ stands for Query for Vaccination Record — is a legacy original-mode query that asks an immunization information system (IIS) or clinical application for a patient's complete immunization history. The core of the message is the QRD segment (Original Query Definition), which carries the patient identifier in QRD-8, a unique query identifier in QRD-4, the query date and time in QRD-1, and the quantity of records requested in QRD-6. An optional QRF segment (Query Filter) supplements the query with patient demographic criteria — name, date of birth, sex, and address — used when the identifier alone is not sufficient to make a definitive match.
The sender is the clinical or public-health system requesting vaccination history — a provider's EHR, a point-of-care application, or a public-health reporting tool. The receiver is the immunization information system that holds the immunization records for the patient population. Because VXQ is a query, it produces no data of its own; it drives the receiver to look up and return records through VXR (single patient match) or VXX (multiple patient matches).
VXQ predates the newer QBP query framework. It remains in active use at immunization information systems — including those conforming to the CDC's HL7 2.5.1 immunization messaging guide — because established IIS infrastructure was built around the original-mode query pattern and many jurisdictions continue to operate on it.
When a VXQ message is sent
A VXQ message is sent whenever a clinical system needs to retrieve vaccination history for a patient: at the point of care before administering a vaccine, during a wellness visit when the provider needs an up-to-date immunization record, or as part of a public-health onboarding workflow that imports prior immunizations before recording a new one with a VXU.
Trigger event
The VXQ message type carries a single trigger event:
VXQ^V01– Query for vaccination record.
The receiver acts on the patient identifier in QRD-8 and, if present, the demographic criteria in QRF, then responds with one of two messages depending on whether the query resolves to a single patient or multiple candidates.
Integration topology
The diagram shows the querying clinical system sending a VXQ through the integration engine to the immunization information system, which responds with VXR or VXX.
{{diagram: clinical system → VXQ query → integration engine → immunization registry → VXR (single match) or VXX (multiple matches) → integration engine → clinical system}}
Typical senders: EHR, point-of-care immunization application, public-health reporting client, school or occupational health system.
Typical receivers: immunization information system (IIS), state or regional immunization registry, clinical data repository with immunization records.
Direction: request/response — the VXQ initiates a synchronous or deferred query, and the registry responds with VXR or VXX.
Segments in a VXQ message
The VXQ_V01 message is compact: a required MSH header, a required QRD query definition, and an optional QRF query filter. 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.
| Segment | Description |
|---|---|
MSH | Message Header. Opens every VXQ message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (VXQ^V01), carries the message control id in MSH-10, and pins the HL7 version. Receivers route on MSH-9 and correlate the eventual VXR or VXX response back to the originating query using MSH-10. |
QRD | Original Query Definition. The heart of the VXQ message. QRD-1 carries the query date and time, QRD-4 carries a unique query identifier that the responding system echoes back in the VXR or VXX so the requester can match response to query, QRD-6 carries the quantity of records requested (typically 999^RD to retrieve all records), and QRD-8 carries the patient identifier list — the primary means by which the registry locates the patient. The deferred response type in QRD-5 tells the registry whether the response is expected immediately or can be queued. |
[QRF] | Query Filter. Optional demographic filter criteria that supplement the patient identifier in QRD-8. The QRF carries patient name, date of birth, sex, and address in its QRF-2 through QRF-9 fields, which the registry uses for probabilistic matching when the identifier alone cannot make a definitive match. Omit QRF when the identifier in QRD-8 is sufficient; include it when the registry is expected to perform demographic-assisted matching. |
[ ] = optional, { } = repeating
The message structure is intentionally minimal. All query logic is expressed through QRD and the optional QRF; the registry derives the scope of the response from the quantity and patient identifier rather than from a rich query grammar. The canonical segment pages carry the full field-by-field detail.
Sample VXQ message
Note. Constructed for illustration. Patient identifiers, query identifiers, dates, and names are fictional.
MSH|^~&|EHR|GREENVALLEY|IISREG|STATEDOH|20260604093000||VXQ^V01^VXQ_V01|QRY20260604001|P|2.5.1
QRD|20260604093000|R|I|QRY20260604001|||999^RD|PT789456^^^GREENVALLEY^MR|VXQ|IMM
QRF|@PID.5.1~SMITH|19750312|M
What this sample shows
The VXQ^V01 in MSH-9 marks a vaccination query. MSH-10 carries the message control id QRY20260604001, which the registry will echo in its VXR or VXX response so the sender can correlate the reply. QRD stamps the query at 20260604093000 (QRD-1), sets the query id to QRY20260604001 (QRD-4), requests up to 999 records (QRD-6), and identifies the patient as PT789456 in the GREENVALLEY system (QRD-8). The QRF supplies supplemental demographic criteria — family name SMITH, date of birth 19750312, and sex M — to help the registry resolve the match if the medical record number alone is not sufficient.
Working with VXQ messages
The patient identifier in QRD-8 is the primary lookup key
The registry's matching logic begins with QRD-8. Supply the most authoritative identifier available — an IIS-assigned patient ID where one exists, or the sending system's medical record number with its assigning authority. A well-formed identifier in QRD-8 reduces the chance of a multi-patient response (VXX) that requires a second round of disambiguation.
Use QRF for demographic-assisted matching
Include the optional QRF segment when the identifier in QRD-8 is not guaranteed to be known to the registry — for example, when the patient has never been registered there, or when the registry assigns its own identifiers that the sending system does not hold. The demographic fields in QRF allow the registry to perform probabilistic matching against name, date of birth, sex, and address, returning a VXX with candidates when more than one patient is a plausible match.
Correlate the response using QRD-4
QRD-4 is the unique query identifier that the registry echoes into its VXR or VXX response. Generate a distinct value for every query, and use it — rather than patient identifiers alone — to match each incoming response to its originating request. This is essential in asynchronous or deferred-response configurations where multiple queries may be in flight simultaneously.
Handle both VXR and VXX responses
A VXQ query can return either a VXR (single patient found, vaccination records included) or a VXX (multiple patient candidates found, no vaccination records — the requester must select a candidate and re-query). Build response handling that distinguishes between the two trigger events and surfaces VXX candidates to the user or routes them through a disambiguation workflow.
Vendor variance. IIS implementations differ in how strictly they enforce the
QRD-6quantity limit and how they populateQRFmatching fields. Some registries ignoreQRD-6and return all records regardless; others cap results at a system-configured maximum. Confirm expected behaviour against the registry's interface specification or the relevant CDC HL7 2.5.1 immunization implementation guide profile.
FHIR equivalent
A vaccination query corresponds conceptually to a FHIR RESTful search on the Immunization resource, filtered by patient identifier — for example, GET /Immunization?patient.identifier=<system>|<value>. The FHIR response delivers Immunization resources in a searchset Bundle, with the patient as a Patient resource reference.
There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for VXQ_V01. 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 VXQ is a query rather than a notification, it has no direct FHIR message equivalent; the conceptual correspondence is to the FHIR RESTful search interaction rather than to a FHIR message. Systems migrating from VXQ-based IIS queries to FHIR should target the Immunization search API defined by the relevant FHIR implementation guide for their jurisdiction.
Common pitfalls
Pitfall. Omitting QRF when the patient identifier is not known to the registry. If the sending system's medical record number is not registered at the IIS, a query carrying only
QRD-8will return no match. Including demographic criteria inQRFgives the registry the information it needs to perform probabilistic matching and return candidates.
Pitfall. Not handling VXX responses. A VXQ query that matches multiple patients produces a VXX, not a VXR. Systems that handle only VXR will silently drop valid responses and leave the user without vaccination history, with no visible error.
Pitfall. Reusing query identifiers across requests. If
QRD-4is not unique per query, correlating responses to their originating requests is unreliable — particularly in deferred-response or asynchronous configurations where responses may arrive out of order.
How Vorro handles VXQ messages
Vorro accepts outbound VXQ queries over MLLP, validates the patient identifier in QRD and the optional demographic criteria in QRF, and routes each query to the configured immunization registry. Vorro correlates responses to their originating requests using the query identifier in QRD-4, routes VXR responses with vaccination records to the requesting application, and surfaces VXX multi-match responses through a configurable disambiguation workflow. Where a FHIR destination is configured, Vorro translates the vaccination records from a VXR response to Immunization resources — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for VXQ_V01.
Related messages
- VXR — the registry's response to a VXQ when exactly one patient match is found; carries the patient's vaccination records.
- VXX — the registry's response to a VXQ when multiple patient candidates match; requires disambiguation before vaccination records can be returned.
- VXU — the unsolicited vaccination record update that reports a newly administered immunization to the registry.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for VXQ_V01
- HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for QRD or QRF
- HL7 Messaging Standard Version 2.5.1 product brief
