Convert - HL7 to FHIR (R4)

POST /convert/v1/hl7tofhirr4

This operation converts one or more HL7v2 messages into a FHIR R4 bundle.

Inputs and Outputs

The input is a single HL7v2.x message for a single patient. Supported message types include:

• ADT
• ORU
• MDM
• VXU
• RSP^K11 immunization query response (MSH-21.1 message profile identifier must be Z32)

The Convert API utilizes context within the messages to intelligently process the message segments. For example, OBX segments may be converted to either Observations or LabObservations depending on the message type.

The output is a FHIR R4 Bundle containing the data parsed from the input, along with an OperationOutcome resource detailing the results (including warnings or errors) of the conversion process. See Output FHIR R4 Bundles for details.

Query Parameters

Data Format

The input is a plaintext HL7 message. You can specify either content-type: application/hl7-v2+er7 or content-type: text/plain in your request header.

You can specify either accept: application/json or accept: application/xml in your request header to get a response in either JSON or XML format.

Default Timezone

Times that carry their own UTC offset are used as given. For times that do not, the Convert API will attempt to infer the timezone based on the information present in the message.

tz Parameter

The optional tz query parameter provides supplementary information to aid in determining the timezone. For example, a timestamp of 202607011200-0700 could mean either Pacific Time or Arizona Time. If the caller knows that the data came from systems in Arizona, it could provide a tz parameter of America/Phoenix to help the system select the appropriate timezone. The tz parameter also serves as a default timezone if no other can be determined from the message.

Timezone Selection

The system will infer a single default timezone for the whole message, using the first of these that is available:

1. UTC offset in MSH-7
2. UTC offset in EVN-2
3. US ZIP code in ZFA-4.5 – Must be a valid 5 or 9 digit ZIP code (including the form #####-####).
4. US state in ZFA-4.4 – Must be a valid two-letter US state/territory abbreviation. ZFA-4.3 (city) must also be populated. When a state has multiple timezones, the tz parameter can be used to advise which to use, as explained above.
5. tz query parameter
6. UTC

The output OperationOutcome always includes an issue naming which of the above supplied the default timezone, or a warning if none did and UTC was used.

Standardization and Uplift

The Convert API standardizes and enhances the output into a consistent format suitable for downstream processing. See Understanding Uplift for details.

Processing Notes

• If more than one message is included in the input, they must all represent data about the same individual.
• If there are multiple messages, they must be listed chronologically.
• If the input includes a mix of ADT and non-ADT message types (or multiple ADT messages), the last ADT message is treated as the source of truth for patient and encounter information.
• Unsupported message types will be ignored and not present with the output. An OperationOutcome error will indicate this in the output bundle.

Example

MSH|^~\&|||||20220308040000||ADT^A01|||2.7
EVN|A01|20220308040000
PID|1||123456||Test^Patient|||||||||||||7890
PV1|1|I||||||||||||||||||||||||||||||||||||||||||20220308040000"

FHIR Bundles are verbose, so the output below just shows a small sample to illustrate how the data is structured. For a more complete example, try out the API in the Developer Portal Sandbox, or refer to the FHIR Specification.

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "Patient",
        ... (patient fields)
      }
    },
    {
      "resource": {
        "resourceType": "Encounter",
        ... (encounter fields)
      }
    },
    ...
    {
      "resource": {
        "resourceType": "OperationOutcome",
        "issue": [
          ... (any processing issues)
      }
    }
  ]
}