HL7 DOC messages return one or more clinical documents in response to a document query — they carry the transcription headers, content, and status of documents such as discharge summaries, operative reports, and consultation notes. A DOC message is the answer to a QRY query for documents: the querying system asks what documents exist for a patient, and the document management system responds with a DOC message that carries the metadata and content for each matching document. This page explains what a DOC message represents, the trigger event that carries it, every segment the message can contain and what each one holds, and how a DOC document response relates to FHIR. Sample content is constructed for illustration with fictional identifiers.
What a DOC message represents
A DOC message — DOC stands for Document Response — communicates that a document management system is returning clinical documents that match a prior query. The core of the message is the TXA segment, which carries the transcription document header for each returned document: it records what type of document it is, when it was authored and authenticated, what its current status is, and the unique identifier that links it to any system that stores or indexes documents. The TXA is not the document content itself — it is the authoritative metadata record for the document, and the content follows in OBX observation segments attached to each document result.
The sender is the document management system or health information system, and the receivers are the systems that display, archive, or act on clinical documents — most often an EHR, a clinical workstation, or a health information exchange. DOC sits downstream of the query: a QRY message asks which documents exist, and the DOC message delivers them. Because the document metadata in TXA is the authoritative record of document status and authentication, consumers should read status and ownership from TXA rather than inferring them from content.
When a DOC message is sent
A DOC message is sent in response to a QRY^T12 document query. The querying system issues the query with patient and date criteria, and the document system responds with a DOC^T12 message that carries one RESULT group per matching patient, and within each RESULT group one DOC_RESULT group per matching document. A query that matches multiple documents produces a single DOC response with multiple document result groups; a query that matches nothing returns a DOC message with an appropriate query acknowledgement code and no result groups.
Trigger event
The DOC message type carries a single trigger event relevant to document retrieval:
DOC^T12– Document response. Sent in reply to aQRY^T12document query and returns one or more clinical documents.
Because DOC has one trigger event, the receiver's handling turns on the contents of TXA — the document type, the status, the authentication state, and the unique document number — rather than on the trigger code in MSH-9.
Integration topology
The diagram shows the querying system requesting documents through the integration engine and the document management system responding with a DOC message.
{{diagram: querying system → QRY^T12 → integration engine → document management system → DOC^T12 → integration engine → querying system / EHR / clinical workstation}}
Typical senders: health information system, document management system, EHR acting as a document repository, transcription platform.
Typical receivers: EHR clinical workstation, health information exchange, document archive, care coordination application.
Direction: solicited response — the DOC message is always triggered by a prior query and flows back to the querying system.
Segments in a DOC message
The DOC_T12 message opens with a header block and query acknowledgement, then carries one or more RESULT groups. Each RESULT group contains a PID for the patient and one or more DOC_RESULT groups. Each DOC_RESULT group opens with the required TXA transcription document header and may carry an optional ORC common order, zero or more OBX observation segments with document content, and an optional DSC continuation pointer. 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 DOC message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (DOC^T12), carries the message control id in MSH-10, and pins the HL7 version. Receivers route on MSH-9 and deduplicate on MSH-10. |
MSA | Message Acknowledgement. Confirms receipt and processing of the originating QRY^T12 query. Carries the acknowledgement code (AA for accepted, AE for error) and echoes the query's message control id so the querying system can correlate the response to its request. Required. |
[{ERR}] | Error. Provides structured error detail when the acknowledgement code in MSA is not AA. Optional and repeating — more than one error segment may be returned when multiple problems were encountered processing the query. |
QAK | Query Acknowledgement. Returns the query tag from the originating request and a query response status code indicating whether results were found (OK), whether no data matched (NF), or whether the query failed (AE). Required and present once. |
QRD | Original Style Query Definition. Echoes the query parameters from the originating QRY^T12 — the query date and time, the format code, the priority, the query id, the quantity limited request, and the who subject filter identifying the patient. Required. |
PID | Patient Identification. Opens each RESULT group and identifies the patient whose documents follow. Carries the patient identifier list in PID-3 and the patient name in PID-5. Required within each RESULT group; the RESULT group itself repeats once per patient matched by the query. |
TXA | Transcription Document Header. The heart of the DOC message and the required segment that opens each DOC_RESULT group. It carries the full metadata record for a single clinical document: the document type in TXA-2 (a coded value such as DS for discharge summary or OP for operative report), the activity datetime in TXA-4, the origination datetime in TXA-9, the edit datetime, the document completion status in TXA-17 which indicates whether the document is dictated, transcribed, authenticated, or legally authenticated, the authentication status in TXA-22, and the unique document number in TXA-12 that serves as the primary business key for the document. TXA-19 carries the document status code: DI (dictated), DO (documented/transcribed), AU (authenticated), or LA (legally authenticated). |
[ORC] | Common Order. When the document is associated with an order — such as a result document tied to a diagnostic order — the ORC carries the order control code and the filler order number that links the document back to its originating order. Optional. |
[{OBX}] | Observation/Result. Carries the actual document content in one or more observation segments. Each OBX carries a segment of the document in its observation value field; the observation value type is typically FT (formatted text) or ED (encapsulated data) for binary content. Optional and repeating — a long document spans multiple OBX segments, each identified by a sequence number in OBX-1. |
[DSC] | Continuation Pointer. When the response is too large to return in a single message, the DSC carries a pointer that the querying system can include in a continuation query to retrieve the next segment of results. Optional. |
[ ] = optional, { } = repeating
The RESULT group from PID through DSC repeats once per patient matched by the query, and the DOC_RESULT group from TXA through DSC repeats once per document matched within that patient's results. The canonical segment pages carry the full field-by-field detail.
Sample DOC message
Note. Constructed for illustration. Patient identifiers, document numbers, dates, and names are fictional.
MSH|^~&|DOCMGR|MERCYGEN|EHR|MERCYGEN|202006151030||DOC^T12^DOC_T12|MSG00047|P|2.5.1
MSA|AA|MSG00031
QAK|Q0031|OK
QRD|202006151030|R|I|Q0031|||20^RD&Records&HL70126|SMITH^JANE^^^||DS^Discharge Summary^HL70270
PID|1||MR98765^^^MERCYGEN^MR||SMITH^JANE^A||19651022|F
TXA|1|DS^Discharge Summary^HL70270|FT|202006141800|1234^JONES^RICHARD^^^MD|202006141800|202006150900||AU^Authenticated^HL70271||DOC-2026-98765-001|202006141800|AU|||||DOC-2026-98765-001.pdf|LA
OBX|1|FT|18842-5^Discharge Summarization Note^LN||Patient Jane Smith was admitted on 14-Jun-2026 for management of acute exacerbation of COPD. She was treated with bronchodilators and systemic corticosteroids and discharged in stable condition on 15-Jun-2026 with outpatient follow-up arranged.||||||F
What this sample shows
The DOC^T12 in MSH-9 marks a document response. The MSA carries AA, confirming the originating query MSG00031 was accepted. QAK returns query tag Q0031 with status OK, indicating results were found. QRD echoes the original query parameters. PID identifies the patient as Jane Smith with medical record number MR98765. The TXA is the heart of the result: it records a discharge summary (DS in TXA-2), the originating provider in TXA-5, the activity datetime 202006141800 in TXA-4, the unique document number DOC-2026-98765-001 in TXA-12, authentication status AU in TXA-19, and legal authentication status LA in TXA-22, confirming the document has been legally authenticated. The OBX carries the formatted text of the discharge summary note keyed to LOINC code 18842-5.
Working with DOC messages
Read document metadata from TXA, not from OBX
The document type, status, authentication state, and unique identifier all live in TXA, not in the observation content. TXA-19 is the authoritative document status code — do not infer status from content text. Index and route on TXA-2 (document type) and TXA-12 (unique document number), and read authentication state from TXA-19 and TXA-22 before deciding whether a document is ready for a clinical record.
Idempotency and deduplication
Use MSH-10, the message control id, as the deduplication key for the DOC message, and treat the unique document number in TXA-12 as the natural business key for each document. Document queries may be replayed after outages, and a repeated TXA-12 should update the existing document record rather than create a duplicate. Compare the edit datetime and document status on the incoming TXA against the stored record — a higher-status incoming document (for example, AU replacing DO) should supersede the earlier version.
Document status progression
TXA-19 carries a status code that reflects where the document sits in its lifecycle: DI (dictated, audio captured but not yet transcribed), DO (documented, transcription complete), AU (authenticated, clinician has approved the document), LA (legally authenticated, the document has been signed for legal purposes). A document management integration should model this progression rather than treating each status as an independent document — receiving a LA status for a TXA-12 that was previously stored as AU is an update, not a new document.
Multi-segment document content
Long documents span multiple OBX segments, each with a unique sequence number in OBX-1. Reassemble the content in sequence-number order rather than message-arrival order before storing or displaying it, and do not assume a maximum OBX count — large operative reports or discharge summaries can produce dozens of OBX segments.
Vendor variance. Not all document systems populate
TXA-17(the unique document file name) orTXA-22(the authentication status) consistently. Some systems send the document content in a singleOBXusing encapsulated data (ED), while others split formatted text across manyFT-typedOBXsegments. Confirm a partner's field usage against their interface specification rather than assuming the base standard.
FHIR equivalent
A clinical document response corresponds to the FHIR DocumentReference resource, with the patient as a Patient resource and, for a messaging exchange, a MessageHeader at the head of a Bundle.
There is, however, no published mapping to lean on for DOC. The HL7 v2-to-FHIR Implementation Guide provides no message map for DOC_T12 and no ConceptMap for the TXA segment. The closest official analogue is MDM_T02, which does have a published Bundle map in the Implementation Guide; MDM_T02 uses the same TXA segment structure and maps conceptually to DocumentReference. A FHIR DocumentReference produced from a DOC message is therefore mapped manually, taking the document type, status, unique identifier, and authentication state from TXA and populating document content from the OBX observation chain.
Common pitfalls
Pitfall. Treating every incoming DOC as a new document. A query replay or a document-status update produces a DOC message with the same
TXA-12unique document number as a previously received document. Storing each message as a new record produces duplicates; useTXA-12as the upsert key and update status and content when a higher-status version arrives.
Pitfall. Ignoring
TXA-19and displaying unauthenticated documents as final. A document with statusDI(dictated) orDO(documented) has not been reviewed or approved by a clinician; presenting it without a status indicator can mislead clinical users. Surface the authentication status fromTXA-19on every document display.
Pitfall. Reassembling OBX content in arrival order rather than sequence order. Multi-segment documents can arrive with
OBXsegments in non-sequential order; sorting byOBX-1before reassembly is required to render the document correctly.
How Vorro handles DOC messages
Vorro receives the DOC response over MLLP or another transport, deduplicates on MSH-10, and routes each document result to every subscribed destination in the format that system expects — the EHR document record, the clinical workstation, and the document archive. Vorro reads document type, status, and authentication state from TXA, uses TXA-12 as the upsert key to handle status progressions without creating duplicates, and reassembles multi-segment document content from the OBX chain in sequence order. Where a FHIR destination is configured, Vorro maps the document to a DocumentReference resource — composed manually, since the v2-to-FHIR Implementation Guide publishes no map for this message.
Related messages
- MDM — the Medical Document Management message that proactively notifies systems of new or updated clinical documents, using the same TXA structure.
- QRY — the original style query message that triggers a DOC^T12 document response.
- ORU — the unsolicited observation result message, which carries observation-based clinical results in a related but distinct pattern from document-based responses.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for DOC_T12
- HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for TXA
- HL7 Messaging Standard Version 2.5.1 product brief
