HL7

Process and send HL7 messages for EHR interoperability. Accept inbound HL7 messages, send lab results, and replay messages.

3 endpoints

Guide

The HL7 endpoints enable healthcare interoperability using HL7 v2.x messaging. BlueHive both receives and sends HL7 messages — accepting inbound messages from EHR systems and sending outbound messages for orders, results, appointments, and documents. This is the primary integration method for clinical systems.

Overview

HL7 (Health Level Seven) v2.x is the most widely used healthcare messaging standard. BlueHive uses pipe-delimited HL7 messages to exchange clinical data with EHR systems like WebChart, Epic, and others. Messages are composed of segments (MSH, PID, ORC, OBR, OBX, etc.) separated by carriage returns.

Supported Message Types

BlueHive supports these HL7 message types:

  • ORM^O01 — Order Message: Send a new order to a provider's EHR
  • ORU^R01 — Lab Results: Send structured lab results with panels and observations
  • ORU^R03 — Document Results: Send results as a base64-encoded document (PDF)
  • SIU^S12 — Schedule Appointment: Book an appointment in the provider's scheduling system
  • ADT^A01/A04/A08 — Patient Registration/Update: Create or update patient demographics
  • MFN^M13 — Master File Notification: Synchronize employer/employee master data
  • MDM^T02 — Document Management: Send documents (lab reports, forms) to EHR systems

Sending HL7 Messages to BlueHive

The POST /v1/hl7 endpoint accepts inbound HL7 messages in multiple formats. BlueHive validates the message, extracts employee/employer data, looks up services, and creates or updates orders automatically. You can send messages as JSON, raw text, or form-encoded data.

Send HL7 via JSON
Post an HL7 message using JSON wrapper
curl -X POST https://api.bluehive.com/v1/hl7 \
  -H "Content-Type: application/json" \
  -d '{
    "message": "MSH|^~\\&|SENDING_APP|SENDING_FACILITY|BLUEHIVE|BLUEHIVE|20260309120000||ORM^O01|MSG001|P|2.3\rPID|1||12345||DOE^JOHN||19800101|M|||123 MAIN ST^^DETROIT^MI^48201||3135551234\rORC|NW|ORD001||||||||^SMITH^JANE\rOBR|1|ORD001||DRUG_TEST_10^10-Panel Drug Screen"
  }'

Send HL7 as Raw Text

For systems that generate raw HL7, you can send the message body directly as text/plain. Each segment should be separated by a carriage return (\r).

Send raw HL7
Post raw HL7 content
curl -X POST https://api.bluehive.com/v1/hl7 \
  -H "Content-Type: text/plain" \
  -d 'MSH|^~\&|LABSYS|CLINIC|BLUEHIVE|BLUEHIVE|20260309120000||ORU^R01|MSG002|P|2.3
PID|1||12345||DOE^JOHN||19800101|M
ORC|RE|ORD001||CM
OBR|1|ORD001||DRUG_TEST^Drug Screen|||20260308|
OBX|1|ST|THC^THC||NEGATIVE||||||F
OBX|2|ST|COC^Cocaine||NEGATIVE||||||F
OBX|3|ST|OPI^Opiates||NEGATIVE||||||F'

HL7 Segment Reference

Understanding the key HL7 segments is essential for building integrations. Here is a reference for the segments BlueHive uses:

MSH — Message Header

Every HL7 message starts with MSH. It identifies the sending/receiving systems, message type, and version.

MSH segment structure
Message Header segment format
MSH|^~\&|SENDING_APP|SENDING_FACILITY|RECEIVING_APP|RECEIVING_FACILITY|YYYYMMDDHHMMSS||MSG_TYPE^TRIGGER|CONTROL_ID|P|VERSION
     |       |              |                  |               |                   |                     |          |                  |    |
     |       |              |                  |               |                   |                     |          |                  |    └─ HL7 version (2.3)
     |       |              |                  |               |                   |                     |          |                  └──── Processing ID (P=Production)
     |       |              |                  |               |                   |                     |          └───────────────────── Message control ID (unique)
     |       |              |                  |               |                   |                     └──────────────────────────────── Message type (ORM^O01)
     |       |              |                  |               |                   └──────────────────────────────────────────────────── Timestamp
     |       |              |                  |               └──────────────────────────────────────────────────────────────────────── Receiving facility
     |       |              |                  └─────────────────────────────────────────────────────────────────────────────────────── Receiving application
     |       |              └────────────────────────────────────────────────────────────────────────────────────────────────────────── Sending facility
     |       └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Sending application
     └───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────── Encoding characters

PID — Patient Identification

The PID segment carries patient demographics. BlueHive uses this to match or create employees.

PID segment example
Patient identification segment
PID|1|MR-12345|EMP001^^^MR||DOE^JOHN^A||19800115|M||White|123 MAIN ST^^DETROIT^MI^48201^US||^^^^^313^5551234||English|M

Field  | Name                    | Example
-------|-------------------------|---------------------------------
PID.1  | Set ID                  | 1
PID.2  | Patient ID              | MR-12345
PID.3  | Patient Identifier List | EMP001^^^MR
PID.5  | Patient Name            | DOE^JOHN^A (Last^First^Middle)
PID.7  | Date of Birth           | 19800115 (YYYYMMDD)
PID.8  | Sex                     | M (M/F/U)
PID.10 | Race                    | White
PID.11 | Address                 | Street^^City^State^Zip^Country
PID.13 | Phone                   | ^^^^^AreaCode^Number

ORM^O01 — Order Message (Full Example)

The Order Message is used to send new orders to a provider's EHR. It includes patient demographics (PID), visit info (PV1), order control (ORC), and order details (OBR).

Complete ORM^O01 message
Send a new drug test order to a provider EHR
MSH|^~\&|BLUEHIVE|ACME_CORP|WEBCHART|CLINIC_A|20260309150000||ORM^O01|20260309150000|P|2.3
PID|1|01360320030614|14704||SMITH^JANE^M||19900515|F|||2905 SCOTTY DR^^PLEASANT LAKE^IN^46779||2604755459
PV1|0001|O-EL||||100^SHIPE^TERRY|||||MED||||||100^SHIPE^TERRY|O|1215166
ORC|NW|2033818||||||||^ORDERING^DOCTOR
OBR|1|2033818||DRUG_TEST_10^10-Panel Drug Screen|||20260309150000|||||||||||||||F

ORU^R01 — Lab Results (Full Example)

Lab results use ORU^R01 with structured OBR (order/panel) and OBX (observation) segments. Each panel (OBR) can contain multiple observations (OBX) with numeric, text, or coded values.

Complete ORU^R01 message
Send lab results with multiple observations
MSH|^~\&|LAB|AHL|WEBCHART|22725544|20260309062503||ORU^R01|00000000000660416160|P|2.3
PID|1|MR-2031599|AH105691E|17470|FETT^BOB^A||19670701|M|||||^^^^^765^2300428|||0664430
ORC|RE|17470|AH105691E||CM|||||||^HAKE^RITA^D
OBR|1|17470|AH105691E|34392SB=^ELECTROLYTE PANEL^^34392SB=^ELECTROLYTE PANEL|||20260308092400|||||||20260309034900|^HAKE^RITA^D|||||||||20260309062400|||F
OBX|1|NM|25000400^SODIUM^^25000400^SODIUM^QDIAHL||137|mmol/L|135-146|N|||F|||20260309062400|BH^^L
OBX|2|NM|25000500^POTASSIUM^^25000500^POTASSIUM^QDIAHL||4.1|mmol/L|3.5-5.3|N|||F|||20260309062400|BH^^L
OBX|3|NM|25000600^CHLORIDE^^25000600^CHLORIDE^QDIAHL||102|mmol/L|98-110|N|||F|||20260309062400|BH^^L
OBX|4|NM|25000700^CO2^^25000700^CO2^QDIAHL||24|mmol/L|20-31|N|||F|||20260309062400|BH^^L

OBX Field Reference:
  OBX.1 = Set ID (sequential within panel)
  OBX.2 = Value Type (NM=Numeric, ST=String, TX=Text, ED=Encapsulated Data)
  OBX.3 = Observation Identifier (code^name)
  OBX.5 = Observation Value
  OBX.6 = Units
  OBX.7 = Reference Range
  OBX.8 = Abnormal Flags (N=Normal, H=High, L=Low, A=Abnormal)
  OBX.11 = Result Status (F=Final, P=Preliminary, C=Corrected)

SIU^S12 — Schedule Appointment (Full Example)

The scheduling message books an appointment in a provider's EHR. It includes the scheduling segment (SCH), patient info (PID), visit info (PV1), resource group (RGS), location (AIL), and personnel (AIP).

Complete SIU^S12 message
Book a clinic appointment
MSH|^~\&|BLUEHIVE|EMPLOYER|MIE|CLINIC|20260309145339||SIU^S12|000001|P|2.3.1
SCH|97895||||||Office Visit|SHORTAPT^Drug Screen Appointment|||^^^20260315114000||||||||||||||BOOKED
PID|1|10012|10012^^^MR&1.2.840.114398.1.668.1&ISO^MR||JONES^EMILY^^^^^L||20081001|F||White|2501 MERRVALE RD^^ROCKVILLE^MD^20847^US||3015550199^PRN^PH~2025550199^PRN^CP||English|S
PV1|1|O|CLINIC^ROOM1^BED1^FREEMAN||||1^FREEMAN^LUCIUS^B^MD
RGS|1
AIL|1||^^^OF|||||||||BOOKED
AIP|1||4^EDGE^CAROL^D|||||||||BOOKED

Segment Reference:
  SCH.1  = Appointment ID
  SCH.8  = Appointment Reason
  SCH.9  = Appointment Type
  SCH.12 = Start Date/Time (^^^YYYYMMDDHHMMSS)
  SCH.26 = Filler Status Code (BOOKED, CANCELLED, etc.)
  RGS.1  = Resource Group Set ID
  AIL.1  = Set ID (location resource)
  AIP.1  = Set ID (personnel resource)

MDM^T02 — Document Transmission

Use MDM^T02 to send documents (PDFs, lab reports, forms) to an EHR system. The document is base64-encoded in an OBX segment with value type ED (Encapsulated Data).

MDM^T02 document message
Send a PDF document to an EHR
MSH|^~\&|BLUEHIVE|EMPLOYER|WEBCHART|CLINIC|20260309120000||MDM^T02|MSG003|P|2.3
PID|1||EMP001^^^MR||DOE^JOHN||19800115|M|||123 MAIN ST^^DETROIT^MI^48201
PV1|1|O
TXA|1|AR|AP||20260309120000|||||||||DOC001
OBX|1|ED|PDF^Lab Report||^application^pdf^Base64^JVBERi0xLjQKJ...||||||F

TXA Segment (Document Header):
  TXA.1  = Set ID
  TXA.2  = Document Type (AR=Addendum Report)
  TXA.3  = Content Presentation (AP=Application)
  TXA.5  = Activity Date/Time
  TXA.13 = Unique Document Number

OBX with ED (Encapsulated Data):
  OBX.2 = ED (Encapsulated Data)
  OBX.5 = ^content-type^encoding-type^encoding^BASE64_DATA
  Example: ^application^pdf^Base64^JVBERi0xLjQK...

ACK Response

After processing an inbound HL7 message, BlueHive returns an HL7 ACK (acknowledgment). Check the MSA segment for the acknowledgment code — AA (Application Accept) means success.

HL7 ACK response
Successful acknowledgment
MSH|^~\&|BLUEHIVE|BLUEHIVE|SENDING_APP|SENDING_FACILITY|20260309120001||ACK|ACK001|P|2.3
MSA|AA|MSG001

MSA.1 Acknowledgment Codes:
  AA = Application Accept (success)
  AE = Application Error (message accepted but error in processing)
  AR = Application Reject (message rejected)

Sending Results via HL7

The POST /v1/hl7/results endpoint sends lab results or documents via HL7 to all configured outbound interfaces for the employee's brand. Provide the employee ID and a base64-encoded file.

Send results via HL7
Forward results to a provider EHR
import { readFileSync } from 'fs';

const pdfBuffer = readFileSync('./results.pdf');
const base64File = pdfBuffer.toString('base64');

const response = await fetch('https://api.bluehive.com/v1/hl7/results', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    employeeId: '64f1a2b3c4d5e6f7a8b9c0d1',
    file: {
      name: 'lab-results.pdf',
      type: 'application/pdf',
      base64: base64File
    }
  })
});
// BlueHive builds an ORU^R03 or MDM^T02 message and sends it
// to all enabled outbound interfaces for the employee's brand

Replaying Messages

If an outbound HL7 message failed or needs to be re-sent, use the replay endpoint with the original HL7 log ID. You can optionally specify a different destination.

Replay a failed message
Re-send a previously sent HL7 message
curl -X POST https://api.bluehive.com/v1/hl7/replay/LOG_ID_HERE \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": {
      "url": "https://emr.clinic.com/hl7",
      "protocol": "https",
      "username": "hl7user",
      "password": "hl7pass",
      "timeout": 30000,
      "retryAttempts": 3
    }
  }'

Error Handling

Common HL7 processing errors and how to handle them:

  • Missing required segments — Ensure MSH, PID are present at minimum
  • Invalid patient match — PID fields must match an existing employee or provide enough data to create one
  • Service not found — The OBR universal service ID must map to a service in BlueHive
  • Destination unreachable — Check the HL7 system interface URL and credentials
  • ACK with AE/AR — Check the ERR segment in the ACK for specific error details
Chat with Bea