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 or newline-delimited set of HL7v2.7 messages for a single patient. Supported message types include:

  • ADT
  • ORU
  • MDM
  • VXU

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

patientId string

Optional resource ID for the Patient. See programming guide for details.

patientIdentifier string

Optional business identifier for the Patient resource. If specified, patientIdentifierSystem must also be present. See programming guide for details.

patientIdentifierSystem string

System that provided the patientIdentifier. If specified, patientIdentifier must also be present. See programming guide for details.

tz

Specifies the timezone for times in the message that lack a timezone specification. This can be specified as either an IANA or Windows timezone ID (e.g, America/Chicago or Central+Standard+Time.) If not specified, the system will default to the timezone in MSH-7 (if available) or UTC.

Data Format

The input is plain text, so be sure to specify 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.

Message 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

Try It
Try out the operations, with examples, in the Developer Portal Sandbox.
Sample Input
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.

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