HL7 Systems

Register and manage HL7 system integrations. Configure outbound interfaces, manage routing priorities, and monitor system activity.

9 endpoints

Guide

HL7 Systems represent registered EHR/clinical systems that BlueHive communicates with. Each system has a unique identity (sending application + facility), can have multiple outbound interfaces, and controls how messages are routed. Systems can be auto-registered when inbound messages are received or manually created.

System Registration

When BlueHive receives an inbound HL7 message from an unknown sending application, it automatically registers a new system with status "unmapped". An administrator can then review and activate the system, link it to a brand, and configure outbound interfaces.

  • unmapped — Newly auto-registered, needs review
  • active — System is configured and operational
  • disabled — System is temporarily disabled

Creating a System Manually

Register a new HL7 system with outbound interfaces for sending messages to an EHR.

Register an HL7 system
Create a system with an outbound interface
await fetch('https://api.bluehive.com/v1/hl7-systems', {
  method: 'POST',
  headers: {
    'Authorization': 'ApiKey YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Clinic A - WebChart',
    sendingApplication: 'WEBCHART',
    sendingFacility: 'CLINIC_A',
    status: 'active',
    interfaces: [
      {
        name: 'Primary HL7 Endpoint',
        messageTypes: ['ORM^O01', 'ORU^R01', 'SIU^S12', 'MDM^T02'],
        url: 'https://emr.clinica.com/hl7/receive',
        method: 'POST',
        username: 'hl7_user',
        password: 'hl7_pass',
        interfaceName: 'bluehiveadt',
        enabled: true
      }
    ]
  })
});

Interface Routing

Each system can have multiple interfaces, each handling different message types. When BlueHive sends an outbound HL7 message, it finds the first enabled interface that matches the message type. Use the reorder endpoint to control priority.

Interface priority is determined by array order — first match wins. Use the reorder endpoint to change priorities without recreating interfaces.

Managing Interfaces

Add, update, remove, and reorder interfaces on an existing system. Each interface specifies the message types it handles, the destination URL, authentication credentials, and whether it is enabled.

Add a results-only interface
Add an interface that only handles results messages
curl -X POST https://api.bluehive.com/v1/hl7-systems/SYS123/interfaces \
  -H "Authorization: ApiKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Results Endpoint",
    "messageTypes": ["ORU^R01", "ORU^R03"],
    "url": "https://emr.clinic.com/hl7/results",
    "method": "POST",
    "username": "results_user",
    "password": "results_pass",
    "enabled": true
  }'
Chat with Bea