HL7 MFR messages return master file records in response to a query. An MFR message is the reply the master file custodian sends after receiving an MFQ query — it carries the records that match the query, structured by the master file type that was requested. This page explains what an MFR message represents, the trigger events that carry it, every segment the message can contain and what each one holds, and how MFR records relate to FHIR. Sample content is constructed for illustration with fictional identifiers.
What an MFR message represents
An MFR message — MFR stands for Master Files Response — communicates the content of one or more master file records to a requesting application. Master files hold the reference data that clinical systems depend on: staff directories, charge descriptions, locations, service item catalogs, and other tables that change infrequently but must stay consistent across systems. When a system needs to retrieve or refresh those records, it sends an MFQ query; the custodian replies with an MFR carrying the requested data.
The structure of an MFR message is built around two key segments. The MFI (Master File Identification) segment describes the master file as a whole — which file is being returned, the file-level event, and the response level the sender expects. The MFE (Master File Entry) segment identifies each individual record within the file. Following each MFE are the master-file-specific segments that carry the actual content of the record — for example, STF and PRA for staff entries, LOC for location entries, or CDM for charge description entries.
The sender is the system that owns the master file — typically an EHR, an MPI, or a facility's reference data repository. The receivers are the downstream applications that need to populate or refresh their local copies of the same reference data.
When an MFR message is sent
An MFR message is sent in direct response to an MFQ query. The MFQ carries a query definition segment (QRD) specifying which records are needed, and the MFR echoes that QRD back alongside the matching records so the receiver can correlate the response to its request. If the master file contains no records matching the query, an MFR is still returned — with a status in QAK indicating no data found — so the requester receives a definitive answer rather than a timeout.
The MFI-6 response level code in the MFR controls whether the original MFN sender (in a notification scenario) expects record-level acknowledgements via MFK; in the query-response scenario the MFR itself is the data reply and any transport-level acknowledgement is handled separately.
Trigger events
The MFR message type carries one trigger event per master file type, mirroring the MFQ trigger events that prompted the query:
MFR^M01– Master file query response: staff practitioner master file.MFR^M02– Master file query response: staff practitioner master file (with PRA).MFR^M03– Master file query response: test/observation master file.MFR^M04– Master file query response: charge description master file.MFR^M05– Master file query response: patient location master file.MFR^M06– Master file query response: clinical study with phases and schedules.MFR^M07– Master file query response: clinical study without phases but with schedules.MFR^M08– Master file query response: test/observation (numeric) master file.MFR^M09– Master file query response: test/observation (categorical) master file.MFR^M10– Master file query response: test/observation batteries master file.MFR^M11– Master file query response: test/calculated observations master file.MFR^M12– Master file query response: master file notification for OM6 — clinical study master file.MFR^M13– Master file query response: pharmacy/treatment master file.MFR^M14– Master file query response: site-defined master file.MFR^M15– Master file query response: inventory item master file.
Each trigger code matches the corresponding MFQ trigger that initiated the query. The receiver routes on the trigger code in MSH-9 to determine which master file type the response covers and therefore which master-file-specific segments to expect after each MFE.
Integration topology
The diagram shows the requesting application issuing an MFQ query through the integration engine to the master file custodian, which replies with an MFR carrying the requested records.
{{diagram: requesting application → MFQ query → integration engine → master file custodian → MFR response → integration engine → requesting application}}
Typical senders: EHR or hospital information system acting as the master file custodian, MPI (Master Patient Index), reference data repository, laboratory information system.
Typical receivers: downstream clinical applications, pharmacy systems, billing systems, and scheduling systems that need to refresh their local copy of reference data.
Direction: request-response — an MFQ query is sent to the custodian, and the MFR is the direct reply carrying the matching records.
Segments in an MFR message
The MFR message opens with header and acknowledgement segments, echoes the query definition, then carries the master file identification followed by one or more repeating MF groups — each group holding an MFE entry segment and the master-file-specific content segments for that record. 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 MFR message. It names the sending and receiving applications and facilities, stamps the creation time, declares the trigger event in MSH-9 (for example MFR^M02), carries the message control id in MSH-10, and pins the HL7 version. Receivers route on MSH-9 to determine the master file type and deduplicate on MSH-10. |
MSA | Message Acknowledgement. Carries the acknowledgement code and the message control id from the originating MFQ, confirming that the query was received and processed. Required in MFR to close the application-level handshake initiated by the MFQ. |
[{ERR}] | Error. Communicates error details when the query could not be fully satisfied — for example, when an unknown master file ID was requested or when an individual record could not be retrieved. Optional and repeating to report multiple errors in a single response. |
QAK | Query Acknowledgement. Carries the query tag from the originating MFQ and a query response status code indicating whether records were found, no data was found, or an error occurred. Required; receivers use QAK-2 to determine whether to expect data in the MF groups that follow. |
QRD | Query Definition. Echoed from the originating MFQ so the receiver can correlate the response to its request. Carries the query date and time, query format, query priority, query ID, and the what-subjects-filter identifying which records were requested. Required. |
MFI | Master File Identification. Identifies the master file being returned and carries file-level metadata. MFI-1 holds the master file identifier (for example STAFF_LOC for the patient location master). MFI-3 is the file-level event code. MFI-4 is the entered date and time. MFI-5 is the effective date and time from which the returned records are valid. MFI-6 is the response level code, which controls whether the original notification sender expects record-level acknowledgements — AL for all records, ER for errors only, NE for no response expected. Required. |
{MFE} | Master File Entry. Opens each record group and identifies a single record within the master file. MFE-1 carries the record-level event code (typically MAD for add, MDL for delete, MUP for update). MFE-2 is the MFE set ID sequencing the entries within this response. MFE-4 is the primary key value that uniquely identifies the record — for a staff entry this is the practitioner ID, for a location entry the location identifier. MFE-5 carries the primary key value type. Required and repeating — one MFE per record returned. |
[master-file-specific segment(s)] | Record content. The segment or segments that carry the actual data for the master file record identified by the preceding MFE. The specific segments depend on the trigger event: STF (and optionally PRA) for M02 staff/practitioner entries; CDM for M04 charge description entries; LOC for M05 patient location entries; OM1 and related OM segments for M03/M08–M11 observation master entries. These segments are optional within each MFE group — absent for a delete event where only the primary key in MFE-4 is needed. |
[ ] = optional, { } = repeating
The MFE group — from MFE through the master-file-specific segments — repeats once per record returned, so a single MFR message can deliver an entire file's worth of records. The canonical segment pages carry the full field-by-field detail.
Sample MFR message
Note. Constructed for illustration. Staff identifiers, facility names, dates, and names are fictional. This example shows an M02 staff/practitioner response.
MSH|^~&|EHRMASTER|MERCYGEN|CLINAPP|MERCYGEN|20260604093000||MFR^M02^MFR_M02|MSG00088|P|2.5.1
MSA|AA|MSG00055
QAK|QRY20260604001|OK
QRD|20260604093000|R|I|QRY20260604001|||999^RD|@STAFF|||
MFI|PRA^Practitioner Master File^HL70175||UPD|20260604000000|20260604000000|NE
MFE|MAD|1|20260604000000|P200123^SMITH^JANE^^^MD^NPI||CWE
STF|P200123^SMITH^JANE^^^MD^NPI|P200123^NPI|SMITH^JANE^A|P|19750312|F|||123 MAIN ST^^SPRINGFIELD^IL^62701^USA|^PRN^PH^^^217^5550101|||MD^Physician^HL70182|A
PRA|P200123^SMITH^JANE^^^MD^NPI|GEN^General Practice^HL70358|MD|I|||
MFE|MAD|2|20260604000000|P200456^CHEN^DAVID^^^MD^NPI||CWE
STF|P200456^CHEN^DAVID^^^MD^NPI|P200456^NPI|CHEN^DAVID^B|P|19680819|M|||456 OAK AVE^^SPRINGFIELD^IL^62702^USA|^PRN^PH^^^217^5550202|||MD^Physician^HL70182|A
PRA|P200456^CHEN^DAVID^^^MD^NPI|INT^Internal Medicine^HL70358|MD|I|||
What this sample shows
The MFR^M02 in MSH-9 marks a staff/practitioner master file response. MSA carries acknowledgement code AA and echoes the original MFQ's message control id MSG00055, confirming the query was accepted. QAK carries query tag QRY20260604001 with status OK, signalling that matching records were found. QRD is echoed from the MFQ. The MFI identifies the practitioner master file (PRA), with an effective date of 2026-06-04 and response level NE (no record-level acknowledgement expected).
The first MF group opens with an MFE carrying event code MAD (add), set ID 1, and primary key P200123 identifying practitioner Jane Smith. The STF carries her staff record — name, type, date of birth, sex, address, and active status. The PRA adds her practitioner detail — specialty General Practice, provider type MD. The second MF group returns David Chen in the same structure. Neither group carries an ERR, so both records were returned without error.
Working with MFR messages
Correlate the response to its query using QAK and QRD
Use the query tag in QAK-1 and the echoed QRD to match each MFR to its originating MFQ, especially when multiple queries are outstanding concurrently. Check QAK-2 before processing the MFE groups — a status of NF (no data found) means no groups follow and the local cache should not be altered.
Route on the trigger event to select the correct segments
The segments following each MFE depend entirely on the trigger event in MSH-9. An MFR^M02 carries STF and optionally PRA after each MFE; an MFR^M05 carries LOC; an MFR^M04 carries CDM. Parse the trigger code first and configure segment expectations accordingly — do not assume a fixed record layout across different trigger events.
Use MFE-4 as the primary key for upsert logic
MFE-4 carries the primary key value that identifies each record — the practitioner ID, the location identifier, the charge code. Use this field, combined with MFI-1 (the master file identifier), as the natural key for upsert logic: if the record exists locally, update it; if it does not, insert it. The event code in MFE-1 (MAD, MUP, MDL) signals the intended action, but robust implementations treat every received record as an upsert rather than relying solely on the event code.
Respect MFI-5 as the effective date
MFI-5 carries the date and time from which the returned records are valid. When refreshing a local master file, do not apply records whose effective date is in the future until that date is reached. Applying future-dated records immediately can introduce charges, locations, or practitioners that are not yet active.
Vendor variance. The master-file-specific segments following each
MFEare optional for delete events — whenMFE-1isMDL, many senders transmit only theMFEwith its primary key and omit the content segments entirely. Confirm a partner's behaviour for each event type against their interface specification.
FHIR equivalent
The FHIR equivalent of an MFR record depends on the master file type. An M02 staff/practitioner record corresponds to a FHIR Practitioner resource (with an associated PractitionerRole). An M05 patient location record corresponds to a FHIR Location resource. An M04 charge description record corresponds to a FHIR ChargeItemDefinition resource. An M03/M08–M11 observation master record corresponds to a FHIR ObservationDefinition resource.
There is, however, no published mapping to lean on. The HL7 v2-to-FHIR Implementation Guide provides no message map for MFR and no ConceptMap for the MFI or MFE segments. FHIR resources produced from MFR records are therefore mapped manually, deriving the resource type from the trigger event and populating resource fields from the master-file-specific segments (STF/PRA, LOC, CDM, and so on) for each returned record.
Common pitfalls
Pitfall. Processing MFE groups without first checking
QAK-2. A status ofNF(no data found) orAE(application error) means the groups that follow — if any — do not represent valid master file data. Always branch on the query status before iterating over MFE groups.
Pitfall. Assuming the same segment structure for all trigger events. An
MFR^M02and anMFR^M05both carryMFIandMFE, but the content segments are completely different. Hard-coding a single parser for all MFR trigger events will silently misread or discard record content when the trigger changes.
Pitfall. Ignoring
MFI-5, the effective date. Applying records before their effective date can activate practitioners, locations, or charge codes that are not yet valid, causing downstream clinical and billing errors.
How Vorro handles MFR messages
Vorro ingests MFR responses over MLLP or another transport, correlates each response to its originating MFQ using the query tag in QAK-1, and routes the returned records to every subscribed destination. Vorro reads the master file type from MSH-9 and MFI-1, iterates over the MFE groups, and extracts record content from the appropriate master-file-specific segments — STF/PRA for staff, LOC for location, CDM for charge description — applying each record as an upsert keyed on MFE-4. Where a FHIR destination is configured, Vorro maps each returned record to the corresponding FHIR resource (Practitioner, Location, ChargeItemDefinition, and so on), composed manually since the v2-to-FHIR Implementation Guide publishes no map for this message.
Related messages
- MFQ — the master files query that an MFR message responds to.
- MFN — the master file notification that pushes master file updates without a preceding query.
- MFK — the master file acknowledgement returned to confirm receipt of an MFN notification.
Sources
- HL7 v2-to-FHIR IG — message maps index — confirms no message map for MFR
- HL7 v2-to-FHIR IG — segment maps index — confirms no ConceptMap for MFI or MFE
- HL7 Messaging Standard Version 2.5.1 product brief
