How We Built Bidirectional HCHB Integration: Technical Lessons from a Production Platform

Homecare Homebase (HCHB) is the dominant EMR in US home health, used by over 3,000 agencies covering more than two million patients annually. If you are building software that sits alongside a home health agency's clinical workflow, a HCHB integration is not optional — it is the integration. What no vendor documentation tells you is how much complexity lives in the phrase "bidirectional HCHB integration." This post covers what we built, why certain decisions were hard, and what we would do differently today.

What bidirectional actually means in home health

In a home health context, "bidirectional" integration with an EMR like HCHB means two distinct data flows:

Most integrations only do one direction. Inbound ADT processing is comparatively straightforward. The outbound MDM sync is where most teams underestimate the work, because pushing a document into HCHB requires understanding how HCHB organises its patient record structure, which document types it accepts, and how it validates incoming HL7 MDM^T02 messages against its own internal schemas.

The ADT message model and why event ordering matters

HL7 ADT (Admit, Discharge, Transfer) messages are the heartbeat of any hospital or post-acute EMR integration. The relevant event types in home health are A01 (admission), A03 (discharge), A08 (patient update), A11 (cancel admission), and A13 (cancel discharge). Each message carries a set of segments — PID (patient identification), PV1 (patient visit), DG1 (diagnosis) — that must be parsed, validated, and reconciled against your own patient records.

The ordering problem is the first thing that surprises teams. In a high-volume agency, ADT events do not always arrive in the order they occurred. A discharge event (A03) can arrive before the corresponding admission update (A08) if network latency affects different message paths differently. Your integration must handle out-of-order delivery gracefully, either by queuing and reprocessing events based on message timestamps or by building a reconciliation layer that holds events until a consistent patient state can be derived. We implemented a message queue with timestamp-based ordering and a 30-second processing window to allow late-arriving events to fall into the correct sequence before state transitions are applied.

MDM T02: what clinical document sync actually requires

HL7 MDM^T02 (Medical Document Management, original document notification with content) is the message type used to push clinical documents into an EMR. In practice, pushing a document into HCHB via MDM^T02 requires:

The silent rejection issue cost us two weeks of debugging. HCHB's integration layer accepted the message (returned ACK^AA) but the document never appeared in the patient record. The root cause was an MRN format mismatch: we were sending the agency's internal patient ID, but HCHB expected its own generated MRN. The fix required maintaining an explicit patient ID mapping table that resolved between our internal IDs and HCHB's MRNs on every outbound message.

Infrastructure decisions that matter at production scale

HCHB exposes its ADT feed via an HL7 MLLP (Minimum Lower Layer Protocol) connection — a persistent TCP socket, not a REST API. Managing an MLLP connection in production requires handling connection drops and reconnects gracefully, implementing the MLLP acknowledgement handshake correctly (every message requires an explicit ACK before the next is sent), and designing for the reality that HCHB's MLLP servers occasionally become unavailable during their own maintenance windows without advance notice.

We built a dedicated MLLP listener service in Node.js that:

For the outbound MDM sync, we implemented a background job that polls for coordination notes ready to be synced, assembles the HL7 MDM^T02 message, sends it via a separate MLLP connection to HCHB's outbound endpoint, and records the ACK response. Failed sends go into a retry queue with a maximum of 5 attempts before escalation to a dead-letter queue for manual review.

The duplicate detection problem no one warns you about

ADT feeds from HCHB sometimes deliver the same event more than once. This is not a bug — it is documented behaviour in HL7 feeds under certain network conditions. Your integration must detect duplicates and discard them without corrupting application state. The standard approach is to use the MSH-10 (Message Control ID) field as a deduplication key, storing processed message IDs in a lookup table with a TTL. We used a 48-hour TTL, which covers the realistic window for HCHB to re-deliver a missed message without requiring indefinite storage of every message ID ever processed.

What we learned and what we would do differently

The biggest lesson is that HCHB integration work cannot be estimated from documentation alone. The integration guide provides the message structure. It does not tell you about the undocumented document type codes, the MRN format conventions, the specific MLLP server behaviour, or the silent rejection patterns. Budget significant time for an HCHB test environment setup (which requires coordination with HCHB's integration team) and plan for at least four to six weeks of iterative testing against their sandbox before production go-live.

The second lesson is that the outbound direction (your platform → HCHB) is significantly harder than the inbound direction. Most teams build the ADT listener first because it is easier to verify — you can see events arriving and confirm your parsing is correct. The MDM sync requires round-trip verification in the HCHB UI, which is only possible after the integration team has configured your document types in the HCHB environment, adding another scheduling dependency to an already complex project.

If you are building home health software that needs to speak HCHB natively, the core architectural decisions — durable message queue, idempotent processing, explicit patient ID mapping, persistent MLLP connection management — are not optional. They are the difference between an integration that works in testing and one that holds up at production volume with real patient data and real clinical stakes.

Our CareCoordinations platform ships with this architecture in production today. If you are building something similar, our healthcare engineering team has done this work before.