Use a well-tested HL7v2 parsing library for your language (e.g. hl7apy for Python, HAPI for Java, or nHapi for .NET) to deserialize the pipe-delimited message into a structured object model.
Extract the MSH segment to determine message type (e.g. ADT^A01 for admit, ADT^A08 for update) and use this to decide which FHIR operation to perform (create vs. update).
Map PID segment fields to a FHIR Patient resource: PID-3 to identifier, PID-5 to name, PID-7 to birthDate, PID-8 to gender, PID-11 to address.
Map PV1 segment fields to a FHIR Encounter resource: PV1-2 to Encounter.status, PV1-3 to Encounter.location, PV1-44/45 to Encounter.period.
Use a FHIR transaction Bundle to POST both the Patient and Encounter in a single atomic request, referencing the Patient via a conditional URL or fullUrl.
Validate the resulting FHIR resources against US Core or relevant profiles using a FHIR validator before persisting.
Known gotchas
HL7v2 is highly customizable; field usage and local Z-segments vary widely between institutions, so review the sending system's message specification rather than assuming standard field meanings.
Character encoding and escape sequences in HL7v2 (e.g. \F\ for pipe, \S\ for ^) must be decoded before mapping values to FHIR; failing to do so produces corrupt data.
HL7v2 does not enforce vocabulary standardization; coded fields like race or diagnosis may use local codes that require a mapping table to translate to FHIR-expected code systems (SNOMED, ICD-10, etc.).
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp