Skip to content
Engineering guide · facts checked 7 November 2026

HL7 to FHIR conversion, mapped segment by segment

How to turn HL7 v2 messages and C-CDA documents into FHIR R4 resources that pass validation: HL7’s v2-to-FHIR guide, segment and data type maps, terminology, identity, the tools compared, and a conversion pipeline we can build and hand over.

Laptop screen showing source code in a dark-themed code editor
At a glance
  • HL7 v2-to-FHIR guide 1.0.0STU 1, published by HL7 in October 2025
  • Segment-to-resource mapsPID, PV1, ORC/OBR, OBX, AL1, DG1, IN1 and more
  • Terminology before codeLocal codes to LOINC, SNOMED CT and UCUM
  • Output that validatesProfiles checked in CI on real sample messages

What does HL7 to FHIR conversion involve?

HL7 to FHIR conversion turns HL7 v2 messages (ADT, ORU, ORM and others) or C-CDA documents into FHIR R4 resources. Start from HL7’s Version 2 to FHIR Implementation Guide (1.0.0, STU 1): PID becomes Patient, PV1 Encounter, ORC and OBR ServiceRequest and DiagnosticReport, OBX Observation. The mapping is the easy part. Most of the effort goes on terminology (local codes to LOINC, SNOMED CT and UCUM), identifiers, time zones, duplicates and validating against the target profile, such as US Core.

Convert HL7 to FHIR without losing meaning

A converter that runs is not the same as one that tells the truth

Most teams can get a demo converter working in a week. Point Microsoft’s Liquid templates or a Mirth channel at an ADT feed and FHIR JSON comes out. The trouble starts later: a corrected lab result arrives as a second Observation instead of replacing the first, an admission time shifts by five and a half hours, a local test code nobody mapped lands in a field that downstream analytics reads as LOINC, and the same patient appears three times because two feeds use different assigning authorities.

This guide is the engineering view of HL7 to FHIR conversion as of November 2026. It covers what HL7’s official mapping guide gives you and what it leaves to you, a segment-to-resource table, the data types that quietly break things, terminology, identity and idempotency, transaction Bundles, Z-segments, target profiles (US Core, IPS and India’s ABDM), validation, C-CDA documents, and the main tools with their current status. There is a worked ADT^A01 example with the resulting FHIR, and an ORU^R01 walkthrough.

If you would rather hand the work over, we build conversion pipelines as part of our FHIR interoperability and HL7 and EDI integration services, usually on an engine your team already runs. Background on the two standards is in our HL7 vs FHIR guide.

What changes when a v2 message becomes FHIR

An HL7 v2 message reports an event: a patient was admitted, a result was released, an order was cancelled. FHIR stores state: this is the patient, this is the encounter and its current status, these are the results. Converting one into the other is not a format change. Every message has to be applied to what the receiving server already holds, which is why identity, ordering and corrections matter more than field mapping.

C-CDA is different again. A Continuity of Care Document is a snapshot of a record at a point in time, with human-readable narrative and coded entries side by side. Ten documents from the same clinic will contain the same allergy ten times. Converting documents is mostly about extraction and de-duplication.

HL7’s Version 2 to FHIR Implementation Guide: what it gives you

HL7 published the HL7 Version 2 to FHIR Implementation Guide as release 1.0.0, STU 1, on 7 October 2025. It is the current published version, after ballots in 2020 and January 2024. What it contains:

  • Four kinds of map: message structures (ADT_A01, ORU_R01, VXU_V04 and others), segments, data types and code systems. The authors started from v2.9 but say the guide is not tied to one v2 version.
  • Machine-readable form: the maps are authored as CSV spreadsheets and published as FHIR ConceptMap resources, with conditions written in a simple computable syntax and FHIRPath, so an engine can load them as a starting point.
  • Target: FHIR R4 base resources. The guide does not choose a profile such as US Core for you.
  • Implementation considerations worth reading before you write a line of code: every resource in the output Bundle needs a unique id, receivers should read no meaning into those ids, de-duplication should use identifiers, segment action codes need your own rules, and constraints from local v2 guides are out of scope. The US v2.5.1 immunisation guide’s extra OBX segments are its own example.

Treat the guide as the reference for “where does this field go”, not as a converter. It is a specification; you still need a runtime, terminology services, identity rules and tests.

HL7 v2 to FHIR mapping by segment

The targets below are the ones the guide’s segment maps name. The right-hand column is what tends to go wrong in real feeds.

SegmentFHIR R4 target(s) in the guideWatch for
MSH message headerBundle, MessageHeader, ProvenanceMSH-10 control ID is your replay and duplicate key. MSH-4 sending facility becomes one Organization reused across the Bundle.
EVN event typeProvenanceEVN-2 is when the event was recorded, EVN-6 when it happened. Order messages by the right one.
PID patient identificationPatient, also AccountPID-3 repeats, each with its own assigning authority. PID-2 and PID-4 are deprecated but still sent by older systems.
PD1 additional demographicsPatient, ObservationAdds to the same Patient as PID; do not create a second one.
NK1 next of kinPatient.contact or RelatedPersonPick one rule for the whole interface and write it down.
PV1 / PV2 patient visitEncounter, plus Location and Practitioner referencesPV1-19 visit number is missing or reused in many outpatient feeds. PV1-2 patient class drives Encounter.class.
ORC / OBR order and requestServiceRequest, DiagnosticReport, SpecimenPlacer (ORC-2) and filler (ORC-3) numbers become separate identifiers. OBR-25 result status drives the report status.
OBX observationObservation; DocumentReference for embedded documentsOBX-2 value type decides value[x]. OBX-6 units need UCUM. OBX-11 carries corrections.
NTE notesAnnotations on ServiceRequest or Observation; DocumentReferenceComments that change clinical meaning (“haemolysed sample”) must stay attached to the right result.
AL1 / IAM allergiesAllergyIntoleranceAL1-3 is often free text or a local code; severity and reaction are optional and inconsistent.
DG1 diagnosisCondition, Encounter.diagnosis, EpisodeOfCareDG1-6 diagnosis type (admitting, working, final) decides how the Condition should be categorised.
PR1 proceduresProcedureCode system varies by country: CPT, ICD-10-PCS, SNOMED CT or local.
IN1 insuranceCoverage, with the payer as an OrganizationSubscriber relationship and policy numbers are often in Z-segments instead.
RXA administrationImmunizationCVX codes, lot numbers and completion status.
SPM specimenSpecimenMissing in v2.3-era feeds, where specimen data sits in OBR.
MRG mergeAccount, in the guideA patient merge (ADT^A40) is a workflow, not a field map: decide how Patient.link and existing references are handled.

Data types: where conversions quietly go wrong

  • CX to Identifier. CX.4, the assigning authority, has to become a URI in Identifier.system, so keep a table that turns each namespace (“GENHOSP”, “LABSYS”) into a stable URI or OID. CX.5, the identifier type, maps to Identifier.type through v2 table 0203 (MR, VN, NH and so on). Get this wrong and the same patient becomes several.
  • XPN to HumanName. Family name, given names and prefix map directly. XPN.7, the name type, goes through a vocabulary map to HumanName.use. Several names in PID-5 are normal; keep them all.
  • XAD and XTN. Addresses map to Address. For phone numbers, v2.5 and later put the country, area and local number in separate XTN components, so do not rely on the deprecated first component.
  • CWE and CE to CodeableConcept. Each triplet (code, text, coding system) becomes a Coding, and the alternate triplet becomes a second Coding. Map coding system names to URIs: LN to http://loinc.org, SCT to http://snomed.info/sct, and local systems to a URI you own. Never drop the original code.
  • TS and DTM to dateTime or instant. v2 timestamps take the form YYYYMMDDHHMMSS with an optional fraction and an optional offset. FHIR’s dateTime requires a time zone whenever hours and minutes are present. If the sender omits the offset, the converter must apply the sender’s zone with its daylight-saving rules; guessing UTC moves every event. Keep the precision too: a date-only value stays a date, not midnight.
  • NM and SN to Quantity, Range or Ratio. Results such as “<5” or “1:320” need a comparator, a range or a ratio, not a string.
  • XCN to Practitioner. XCN.1 is the ID and XCN.9 its assigning authority, such as an NPI in the US. Create one Practitioner per person and reuse it: the guide notes that the attending doctor in PV1-7 is often also the ordering provider in ORC-12.

Terminology: local codes to LOINC, SNOMED CT and UCUM

Terminology is where most of the calendar time goes, because a clinician or lab lead has to approve every mapping. Plan it as its own workstream, starting in week one.

  • Lab tests: local order and result codes to LOINC. Order codes and result codes are different lists; a panel maps to one LOINC code and each analyte to another. US Core expects LOINC for laboratory result codes.
  • Problems, procedures, specimens and body sites: SNOMED CT where the target profile asks for it, ICD-10 where billing does.
  • Units: free-text units to UCUM, for example “mg/dl” to mg/dL and “10^3/uL” to 10*3/uL. FHIR’s vital-signs profiles require UCUM, and most receivers expect it for lab values too.
  • v2 tables: abnormal flags (table 0078) to Observation.interpretation; result status (table 0085) to Observation.status, with F as final, P as preliminary, C as corrected and W (wrong patient) as entered-in-error; patient class (table 0004) to Encounter.class.

Keep the maps as ConceptMap resources in version control and look codes up through a terminology service or a $translate call, not hard-coded if-statements. Send both codings, local and standard, so a reviewer can always see where a value came from. Codes with no approved mapping go to a review queue, not into production with a guess.

Identity, duplicates and idempotency

A converter will see the same message twice: engines retry, senders resend, and someone will replay a day of traffic after an outage. Design for it.

  • Conditional create and update. Write Patients with PUT Patient?identifier=system|value, or POST with an If-None-Exist header, so a second admission for the same MRN updates rather than duplicates. The same pattern works for Encounter (visit number), ServiceRequest (placer and filler numbers) and DiagnosticReport (filler order number).
  • Stable keys for results. Key an Observation on filler order number plus OBX-3 code plus OBX-4 sub-ID, not on OBX-1, which senders renumber in corrected messages.
  • Out-of-order messages. Compare event times before applying an update, so an A08 delayed in a queue cannot overwrite a newer discharge.
  • Merges, cancels and deletes. ADT^A40 needs a Patient.link rule and a plan for references to the retired record; A11 (cancel admit) and A13 (cancel discharge) change Encounter status rather than delete anything.
  • Patient matching is not the converter’s job. Never match on name and date of birth inside the transform. Send identifiers through, and let a master patient index decide that two records are one person.

Transaction Bundle, batch or one resource at a time?

OutputBehaviourUse it when
Transaction BundleAll entries succeed or none do. Internal references use urn:uuid fullUrls, resolved by the server; conditional URLs find existing records.Our default: one v2 message, one transaction, so a half-applied admission never exists.
Batch BundleEach entry succeeds or fails on its own. Azure’s $convert-data returns this type.Bulk historical loads where partial success is acceptable and failures are reprocessed.
FHIR message BundleMessageHeader first, sent to a $process-message endpoint.Only when the receiver is built for FHIR messaging, which few servers are.
Individual REST callsOne request per resource, in your own order.Very small feeds. You have to handle partial failures yourself.

Keep the original v2 message, unchanged, in an archive keyed by MSH-10, and point a Provenance resource at it. When someone questions a value two years later, you can show exactly what arrived.

Z-segments and local extensions

Almost every production feed carries Z-segments or uses standard fields in non-standard ways. Inventory them from real samples, not the interface specification, then decide field by field: map to a standard element, define a FHIR extension with a StructureDefinition at a URL you control, or drop it with the receiving team’s agreement in writing. Do not hide Z-segment data in free-text notes; nobody will find it, and the validator cannot check it. Publish your extension definitions in the same package as your profiles so validation knows about them.

Choosing the target profile: US Core, IPS or ABDM

TargetCurrent version (7 Nov 2026)Use it for
US Core9.0.0, published May 2026, aligned to USCDI v6. ONC certification still uses US Core 6.1.0 and USCDI v3 as the baseline, required since 1 January 2026; newer pairs up to 9.0.0 and USCDI v6 are allowed through ONC’s Standards Version Advancement Process.Data that US certified EHRs, payers or patient-access apps will read. Match the version your receiving server states in its CapabilityStatement, not the newest one.
International Patient Summary (IPS)2.0.1, an errata release of STU 2, June 2026Cross-border or cross-organisation patient summaries as Composition-based document Bundles.
ABDM FHIR guide (India)6.5.0 from NRCeS, May 2025Health records shared through India’s Ayushman Bharat Digital Mission: DiagnosticReportRecord, OPConsultRecord, DischargeSummaryRecord and others, each a document Bundle. See our ABDM integration page.
Base FHIR R4 only4.0.1An internal analytics store that only your own team reads. Even then, constrain it with your own profiles.

Validating converted FHIR

  1. Structural and profile validation. Run the HL7 FHIR Validator (validator_cli.jar, updated several times a month) with your target implementation guide packages loaded, or call $validate on HAPI FHIR or a cloud FHIR service. Errors fail the build; warnings are tracked and reduced.
  2. A corpus of real messages. Collect a few hundred de-identified production messages covering every trigger event, every OBX value type and the known oddities. Convert the whole corpus on every change, in CI.
  3. Content checks. Validation proves the shape, not the meaning. Compare source and output field by field for a sample, and have a clinician review a random set of converted results, including corrected ones.
  4. Counts. Messages in, resources out, rejects and review-queue items per day, on a dashboard someone looks at.
  5. Server conformance. If the converted data is served through a US certified API, Inferno test kits check the API and profiles end to end. They test the server, so they complement the steps above rather than replace them.

C-CDA to FHIR conversion

HL7’s C-CDA on FHIR Implementation Guide reached 2.0.0 (STU 2) in June 2026. That release dropped the document profiles and is now a mapping guide, with pages in both directions, C-CDA to FHIR and FHIR to C-CDA, for allergies, encounters, immunisations, medications, notes, participations, patient, problems, procedures, results, social history and vital signs, with ConceptMaps for the vocabularies. Start there rather than inventing your own section maps.

What makes documents harder than messages:

  • Repetition. Every CCD restates the whole problem and medication list. Match entries across documents on their entry IDs and codes before creating anything, or the record fills with copies.
  • Narrative versus entries. The text a clinician reads and the coded entries can disagree, and some sections are narrative only. Keep the original document as a DocumentReference with the XML attached, and convert the coded entries.
  • nullFlavor and templates. Missing values are explicit (nullFlavor), and the same section can appear under different template versions. The converter must recognise both.
  • Document or discrete data? Some receivers want a FHIR document (a Composition-based Bundle); most clinical stores want discrete AllergyIntolerance, Condition and MedicationStatement resources. Decide per receiver.

HL7 to FHIR tools compared (status on 7 November 2026)

ToolWhat it doesStatus checked 7 Nov 2026Fits when
Mirth Connect or Open Integration EngineIntegration engine: MLLP listeners, queues, retries, JavaScript transformers; you write the FHIR mapping, often with HAPI FHIR classes.Mirth Connect is commercial from 4.6; 4.5.2 was the last open-source release. The community fork, Open Integration Engine, released 4.7.0 on 21 October 2026 under MPL-2.0.You already run v2 interfaces on it. Conversion becomes one more channel with the same monitoring. See Mirth Connect services and Mirth Connect migration.
Microsoft FHIR-ConverterOpen-source engine with Liquid templates: HL7 v2 (templates based on v2.8), C-CDA, JSON and STU3 to R4, plus FHIR to HL7 v2 in preview.MIT licence, not archived. Last tagged release v7.0, June 2024; maintenance commits continue (November 2026). Its container API is still labelled preview.You want templates as a starting point and will own and test your copy of them.
Azure Health Data Services $convert-dataThe same Liquid templates as an operation on the FHIR service; returns a batch Bundle that you then load.Documented (August 2026). Microsoft says its default templates are unsupported and not intended for production; host your own copy in Azure Container Registry. Azure API for FHIR was retired on 30 September 2026.Your FHIR store is already on Azure and you will maintain your own templates.
Google Cloud Healthcare APIHL7v2 stores ingest messages through an MLLP adapter, parse them and publish Pub/Sub notifications; FHIR stores hold the result.The HL7v2 store does not convert to FHIR by itself. Google’s reference HL7v2-to-FHIR samples use Whistle 1, which Google marks as an unsupported legacy version; its managed route is the Healthcare Data Engine solution.You are on Google Cloud and will build or buy the mapping layer.
AWS HealthLakeManaged FHIR R4 data store with SMART on FHIR and bulk export.Its Data Transformation Agent (preview) converts C-CDA and CSV to FHIR R4. HL7 v2 is not on its list, so v2 needs your own pipeline in front.You are on AWS, especially for C-CDA. Pair it with an engine or code for v2.
LinuxForHealth hl7v2-fhir-converterJava library with YAML templates, originally from IBM.Apache-2.0. Last release 1.1.1, September 2024; occasional commits (February 2026).A Java team wants a library to extend, and accepts a slow upstream.
HAPI FHIR and HAPI HL7v2Java libraries: v2 parsing, the FHIR R4 model, a validator and a full FHIR server.HAPI FHIR 8.x, released every few weeks; HAPI HL7v2 2.6.0 (February 2025).You want full control in code, or a self-hosted FHIR server.

None of these removes the work in the earlier sections. Templates and cloud operations save the first few weeks of field mapping; terminology, identity rules, Z-segments and validation are yours whichever tool you pick. We are not a reseller or partner of any vendor in this table.

Worked example: ADT^A01 to Patient and Encounter

Illustrative, not client work. The patient, hospital and identifiers are invented. The sender does not include a time-zone offset, and the interface specification says it is in India Standard Time.

MSH|^~\&|ADT1|GENHOSP|FHIRCONV|GENHOSP|20261107083015||ADT^A01^ADT_A01|MSG000123|P|2.5.1
EVN|A01|20261107083000
PID|1||884512^^^GENHOSP^MR||Sample^Asha^K^^Ms||19880614|F|||12 Lake View Road^^Chennai^TN^600017^IND^H||^PRN^PH^^91^44^24345678
PV1|1|I|WARD3^305^B^GENHOSP||||D4521^Iyer^Anand^^^Dr^^^GENHOSP|||MED|||||||||V77881^^^GENHOSP^VN|||||||||||||||||||||||||20261107082500

The converter produces one transaction Bundle. Abridged: in production we also create Practitioner and Location resources, a Provenance for the message, and reference them.

{
  "resourceType": "Bundle",
  "type": "transaction",
  "entry": [
    {
      "fullUrl": "urn:uuid:1d0b6c2e-5f3a-4c8e-9a71-2b6f0e4d8a10",
      "resource": {
        "resourceType": "Patient",
        "identifier": [{
          "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "MR" }] },
          "system": "https://genhosp.example.org/fhir/sid/mrn",
          "value": "884512"
        }],
        "name": [{ "use": "official", "family": "Sample", "given": ["Asha", "K"], "prefix": ["Ms"] }],
        "telecom": [{ "system": "phone", "value": "+91 44 2434 5678", "use": "home" }],
        "gender": "female",
        "birthDate": "1988-06-14",
        "address": [{ "use": "home", "line": ["12 Lake View Road"], "city": "Chennai",
                      "state": "TN", "postalCode": "600017", "country": "IND" }]
      },
      "request": { "method": "PUT",
                   "url": "Patient?identifier=https://genhosp.example.org/fhir/sid/mrn|884512" }
    },
    {
      "fullUrl": "urn:uuid:7c4e2a9b-0d6f-4b3e-8f15-a9c2d7e61b42",
      "resource": {
        "resourceType": "Encounter",
        "identifier": [{
          "type": { "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v2-0203", "code": "VN" }] },
          "system": "https://genhosp.example.org/fhir/sid/visit",
          "value": "V77881"
        }],
        "status": "in-progress",
        "class": { "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "IMP",
                   "display": "inpatient encounter" },
        "subject": { "reference": "urn:uuid:1d0b6c2e-5f3a-4c8e-9a71-2b6f0e4d8a10" },
        "participant": [{
          "type": [{ "coding": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
                                  "code": "ATND" }] }],
          "individual": { "display": "Dr Anand Iyer (D4521)" }
        }],
        "period": { "start": "2026-11-07T08:25:00+05:30" },
        "location": [{ "location": { "display": "WARD3, room 305, bed B" } }]
      },
      "request": { "method": "PUT",
                   "url": "Encounter?identifier=https://genhosp.example.org/fhir/sid/visit|V77881" }
    }
  ]
}

The decisions behind it:

  • GENHOSP in CX.4 became a URI from the namespace table, and MR and VN became Identifier.type codes from table 0203.
  • PV1-2 “I” became Encounter.class IMP. An A01 means the patient is in hospital, so the status is in-progress.
  • PV1-44 had no offset, so the configured zone was applied: 08:25 became 08:25:00+05:30, not 08:25 UTC. A US sender would need its zone’s daylight-saving rules as well.
  • Both resources use conditional PUTs, so replaying MSG000123 changes nothing, and a later A08 updates the same records.
  • The Encounter points at the Patient through the urn:uuid; the server swaps in the real id when it commits the transaction.

ORU^R01 to DiagnosticReport and Observations

A lab result message follows the same pattern with more decisions per field. OBR becomes a DiagnosticReport, keyed on the filler order number, with its code from OBR-4 (a LOINC panel code after terminology mapping) and its status from OBR-25. Each OBX becomes an Observation referenced from DiagnosticReport.result:

  • OBX-2 picks the value type: NM to valueQuantity with a UCUM unit from OBX-6, CWE to valueCodeableConcept, ST or TX to valueString, SN to a Quantity with a comparator or a Range, and ED (an embedded PDF) to an attachment in DiagnosticReport.presentedForm or a DocumentReference.
  • OBX-7, the reference range, goes to referenceRange; keep the text when it does not parse into numbers. OBX-8 abnormal flags go to interpretation, OBX-14 to effectiveDateTime and OBX-11 to status.
  • A corrected result (OBX-11 “C”, OBR-25 “C”) updates the existing Observation found by its key and sets status corrected. It must never create a second result for the same test.
  • NTE segments under an OBX become Observation.note on that result, not on the report.

Pitfalls we see most often

  1. Mapping from the interface specification instead of a week of real messages.
  2. Treating missing time-zone offsets as UTC.
  3. Creating a new resource for every message instead of conditional updates, so replays and corrections duplicate data.
  4. Dropping the original local code once a standard code is found, or sending an unreviewed guess.
  5. Free-text units in valueQuantity, which fail validation and break graphs.
  6. Default templates in production with no tests, then a platform update changes the output.
  7. Assigning authorities that differ between feeds (“GH”, “GENHOSP”, an OID), so one person becomes three Patients.
  8. No archive of the original message, so nobody can prove what the sender actually said.
  9. Validating against base FHIR when the receiver enforces US Core or ABDM profiles.
  10. No review queue: unmappable messages are either silently dropped or loaded with gaps.

How a conversion project runs, with effort

Illustrative, not client work: one hospital’s ADT and ORU feeds converted into a FHIR server that enforces US Core, on the hospital’s existing integration engine. Effort is in engineer-days and does not include the clinical reviewer’s time for terminology sign-off.

PhaseWhat happensTypical effort
Samples and scopeA week of de-identified messages per feed, trigger events listed, target profiles and server confirmed2–4 engineer-days
Mapping specificationField-level maps based on the v2-to-FHIR guide, identity and ordering rules, Z-segment decisions4–6 engineer-days
TerminologyLocal test codes to LOINC, units to UCUM, flags and statuses; ConceptMaps in version control5–10 engineer-days
BuildEngine channels or service, transaction Bundles, archive and Provenance, review queue, alerts8–14 engineer-days
ValidationValidator in CI, corpus replay, field-by-field comparison, clinician spot check4–6 engineer-days
Parallel run and go-liveLive traffic converted alongside the existing flow, daily comparison, then cutover3–5 engineer-days

Total: roughly 26–45 engineer-days over six to eight weeks. What stretches it: a long tail of local test codes, feeds with no stable visit number, and a receiving server that enforces profiles nobody tested against early.

Packages

HL7 to FHIR conversion packages

Typical effort in engineer-days. We confirm a fixed price per phase after reviewing your sample messages or documents.

Mapping specification

The problem

You have feeds and a target, but no agreed field-level mapping, and every developer reads the v2 specification differently.

How we do it

We analyse a week of your real messages, write the segment and data type maps against HL7’s v2-to-FHIR guide and your target profiles, set the identity and ordering rules, list the terminology gaps and Z-segment decisions, and agree it all with the receiving team. Typical effort: 5–10 engineer-days per message family such as ADT or ORU.

What you get

  • Mapping spreadsheet per message type
  • Identity, ordering and correction rules
  • Terminology gap list
  • Z-segment and extension decisions
How it runs

How a conversion engagement runs

For one feed. More feeds add build time, not more stages.

Week 1

Samples and target

De-identified sample messages or documents, the receiving server and its profiles, and the people who will sign off terminology.

Weeks 1–2

Mapping specification

Field-level maps, identity and correction rules, Z-segment decisions and a terminology gap list, agreed with the receiving team.

Weeks 2–5

Build and terminology

The conversion on your engine or as a service, ConceptMaps reviewed by your clinician, validation and replay in CI.

Weeks 5–7

Parallel run and handover

Live traffic converted alongside the current flow, daily comparison, cutover, then a runbook and handover to your team.

Senior engineers firstYour first call is with someone who will do the work, not a sales script.
You own everythingCode, configuration, reports and documentation stay in your accounts and are handed over.
We run our own products15 live platforms we build and operate, so we feel production pain too.
Honest about fitIf a cheaper route or another provider suits you better, we will say so.
FAQ

HL7 to FHIR conversion: common questions

Parse each message, map its segments to FHIR R4 resources using HL7’s Version 2 to FHIR Implementation Guide as the reference (PID to Patient, PV1 to Encounter, OBR to DiagnosticReport, OBX to Observation), translate local codes to standard terminologies, and load the result as a transaction Bundle with conditional updates so replays and corrections do not create duplicates. Validate the output against your target profile before it goes live.

Yes. HL7 published the Version 2 to FHIR Implementation Guide as release 1.0.0, STU 1, in October 2025. It maps message structures, segments, data types and code systems to FHIR R4 and publishes the maps as ConceptMap resources. It is a reference specification, not a converter, and it targets base FHIR rather than profiles such as US Core.

Use the mapping pages in HL7’s C-CDA on FHIR Implementation Guide, which reached 2.0.0 in June 2026, for the sections you need. Keep the original document as a DocumentReference, convert the coded entries to discrete resources, and match repeated entries across documents so the same allergy or medication is not loaded many times.

You can, but treat the templates as your own code. Microsoft says the default templates for $convert-data are unsupported and not intended for production, and recommends hosting your own copy. The open-source FHIR-Converter is MIT-licensed and still maintained, though its last tagged release was in June 2024. Either way you need your own tests, terminology and identity rules.

Mirth Connect, and its open-source fork the Open Integration Engine, give you listeners, queues, retries and transformers, but not a ready-made HL7 to FHIR map. You write the mapping in a channel, often using HAPI FHIR classes, following the v2-to-FHIR guide. Its strength is that conversion runs beside your existing interfaces with the same monitoring.

FHIR requires a time zone on any dateTime that includes hours and minutes, while HL7 v2 makes the offset optional. If the sender omits it, apply the sender’s configured zone with its daylight-saving rules. Never assume UTC, and keep date-only values as dates rather than midnight timestamps.

For one feed such as lab results, our typical range is 15 to 30 engineer-days including a parallel run, over about five to seven weeks. Terminology sign-off by your clinician or lab lead often sets the pace. We confirm a fixed price per phase after reviewing your sample messages.

The one your receiver enforces. In the US that is usually a US Core version; certified EHR APIs have US Core 6.1.0 as their baseline, and US Core 9.0.0 is the latest. Cross-border summaries use the International Patient Summary, and Indian records shared through ABDM use the NRCeS FHIR guide, currently version 6.5.0.

Last updated