The Interface List Is the Project: HL7, FHIR, and the 2008 Financial System

The functional requirements get the attention. Nine hundred rows about ordering, charting, scheduling, and billing, each carefully scored, each argued over in working sessions.

Then there is a small table near the back listing the other systems this one has to talk to. Eight rows, maybe twelve. No scoring. Often no version numbers filled in.

That table is the project. Everything else is configuration.

This is part two of a series. Part one covered the requirements worksheet itself; part three covers national-scale federation.

What's actually on the list

For a county health or behavioral health agency, the interface matrix is not mostly clinical. It's mostly money and identity:

| System | Direction | Why |

|---|---|---|

| General ledger / cash receipts | both | Payments received post to the chart of accounts |

| Payroll & time reporting | both | Push worked time, pull accrual balances |

| Accounts payable | both | Claims and vendor payments |

| Community services management | receive | Claims from partner programs |

| State Medicaid MIS | both | Eligibility, claims, remittance |

| State payment portal | both | Payment posting |

| Public web services | send | Transparency / checkbook reporting |

| Every module of the EHR itself | both | The "natively integrated" claim |

Clinical exchange — labs, pharmacy, immunization registries, health information exchange — sits alongside this, but the ones that sink schedules are usually the financial and identity integrations, for a reason worth stating plainly: clinical interfaces have standards and the financial ones don't.

A lab result has HL7 v2 and increasingly FHIR. A prescription has NCPDP SCRIPT. An immunization submission has a state registry spec. But "post cash receipts to the county general ledger" has whatever the general ledger's vendor decided in 2008.

The version column is the estimate

Here is the thing to internalize about interface matrices: the version column is doing more work than the entire criticality column.

These lists routinely name platforms that are fifteen to twenty years old — a financial package built on a long-superseded development stack, a database release many years past end of support, a "proprietary" platform with no version recorded because nobody left knows it. Sometimes the version cell just reads *TBD*.

Two rows can look identical in the spreadsheet and differ by an order of magnitude in effort:

Row A:  Lab system      | v2024 | REST + FHIR R4 | BOTH | Critical
Row B:  Cash receipts   | 2008  | SQL 2008       | BOTH | Critical

Row A is a week of work against documented endpoints with a sandbox. Row B is: no API, no sandbox, no test environment, a vendor who may no longer support the release, a database you're going to be tempted to write to directly, and an institutional memory that lives in one person's head.

Estimate the interface matrix before you estimate anything else, and estimate it per-row with the version in hand. An interface list with empty version cells is not an interface list; it's a request for one.

The four integration patterns, and when each is a mistake

Every row on that matrix will end up as one of four patterns. Choosing wrong is where the multi-year overruns start.

1. Direct database access

Reach into the other system's database and read (or worse, write) its tables.

Fast to build, and a permanent liability. You've coupled to an internal schema with no contract, no versioning, and no notification when it changes. The other vendor's routine patch becomes your outage. Writes are worse than reads by a wide margin, because you're bypassing every invariant their application layer enforces.

Legitimate use: read-only, against a reporting replica, for a system you control or one that's genuinely frozen. Everything else: treat as technical debt taken deliberately, with a written plan to retire it.

2. File exchange (the batch that runs at 2 a.m.)

Drop a flat file on a share or SFTP endpoint; the other side picks it up on a schedule.

This is the pattern most public sector integrations actually use, and it deserves less contempt than it gets. It's observable, replayable, survives the other system being down, and any analyst can open the artifact and see what happened. For financial postings that reconcile daily, batch is frequently the *correct* answer, not a legacy compromise.

Its real failure modes are specific and preventable:

• No idempotency. The file gets picked up twice and the postings double. Every batch record needs a stable business key and the consumer needs to reject a key it has already processed.
• No negative acknowledgment. Success is silence and failure is also silence. If the only way you learn a batch failed is a clinician noticing, you don't have an interface; you have a hope.
• Partial-file semantics undefined. Row 400 of 900 is malformed. Does the batch abort, skip, or quarantine? Decide this in the spec, not during the incident.

3. Message-based (HL7 v2)

The workhorse of clinical interoperability for three decades. Pipe-delimited segments over a socket, with an acknowledgment. ADT for admissions and demographics, ORM/ORU for orders and results, DFT for billing detail, SIU for scheduling.

HL7 v2 is often described as a standard, and that's generous. It's a framework for negotiating a standard bilaterally: enormous optionality, Z-segments for anything vendors wanted to add, and site-specific conventions everywhere. Two systems that both "support HL7 v2" still require an interface build.

What that means for the schedule: each HL7 interface is its own small project with its own specification document, test cycle, and go-live. Budget them individually. A matrix with nine BOTH rows is nine of these, not one integration workstream.

4. API-based (FHIR and REST)

The modern answer, and increasingly the regulatory one. FHIR models health data as resources — Patient, Encounter, Observation, MedicationRequest — over ordinary REST with JSON.

Where it genuinely wins: read access to discrete data, patient-facing apps, and anything that needs to be queried on demand rather than pushed on a schedule. Where teams get surprised: FHIR is a *data model plus API*, not a workflow engine. It gives you a clean way to ask for a patient's medications. It does not give you an agreed process for reconciling those medications between two systems that disagree — that's still yours to design.

Also: an interface being FHIR does not make it interoperable in the way non-engineers hear that word. Two conformant servers can both be correct and still not exchange usefully, because conformance is about structure and the meaning lives in the terminology bindings. Which brings us to the actual hard part.

Identity is the hard part, and there is no national answer

Every interface above assumes both sides agree on who the patient is. In American health care, that assumption is unfunded.

HIPAA called for a unique national patient identifier in 1996. Since fiscal 1999, an appropriations rider has forbidden HHS from spending a dollar to adopt one, and it has been renewed every year since. So identity resolution is probabilistic, and the industry numbers on getting it wrong are not small: roughly $1,950 in repeated care per inpatient stay from duplicate records, about 35% of denied claims traceable to identification errors, and something over $6.7B annually system-wide.

Practically, this means every multi-system deployment needs a master patient index, and the MPI needs:

• A deterministic path where one exists. Within a single agency you usually have a local medical record number. Use it, and make it the primary key of the integration rather than re-matching demographics on every message.
• A probabilistic path with a tuned threshold and — critically — a manual review queue for the middle band. The failure mode is not the algorithm; it's an organization with no staffed process for the ambiguous matches, so they silently become duplicates.
• A merge/unmerge capability that is auditable and reversible. Merges get made in error. A merge you cannot undo is a data-loss event that arrives disguised as data quality work.
• A policy for identity change. Names change, genders change, guardianship changes. If the design assumes demographic stability, it will quietly mis-file records for exactly the populations most likely to be underserved.

Consent is a second identity problem

Then there is the category that makes behavioral health integration structurally different from general medical integration: some of the data is not allowed to flow with the rest of it.

Substance use disorder records created by federally-assisted programs fall under 42 CFR Part 2, which is materially stricter than HIPAA. The regulation contemplates *data segmentation* — the ability to hold and exchange the protected subset separately, under its own consent. Recent rulemaking simplified consent substantially, allowing a single consent covering future treatment, payment, and operations uses rather than one per disclosure.

The engineering reality is the part that gets skipped in vendor demos: most electronic health records and health information exchanges do not meaningfully support segmentation. A program without segmentation and consent management cannot participate in integrated care models without either over-disclosing or opting out.

So when the requirements worksheet asks whether the system supports role-based and document-level security, the question behind the question is: *can this system hold a category of record that follows different disclosure rules, tag it durably, carry the tag across an interface, and honor it on the receiving side?* That's a very different capability from "we have permissions," and it's worth a scripted demo rather than a checkbox.

What to specify, per row, before you sign anything

The interface matrix as usually written has: system, vendor, version, direction, criticality. That's not enough to build or price. What's needed per row:

System / vendor / version / support status (is the release still supported?)
Direction (send / receive / both)
Pattern (db / file / HL7 v2 / API) and WHY that pattern
Trigger + frequency (real-time on event, hourly, nightly, on-demand)
Volume (records per run, peak)
Identity key (what field joins the two sides — and who owns it)
Error handling (retry policy, dead-letter destination, WHO gets paged)
Idempotency key (what makes a replay safe)
Test environment (does one exist on the other side? — this is a yes/no that changes the estimate)
Owner on the other side (a named human, not a department)
Data classification (does anything here carry Part 2 or equivalent restrictions?)

Two of those lines do most of the work.

"Does a test environment exist on the other side?" If the answer is no, you are going to test in production against a live financial system, and you should know that during procurement rather than during go-live weekend.

"Owner on the other side — a named human." Interfaces don't fail on protocol. They fail because the person who understood the legacy system retired and nobody replaced them in the RACI. If a row can't name a person, that row's risk rating is understated no matter what the criticality column says.

The requirement that decides your architecture

One line in the technical tab quietly determines everything above:

All system modules must natively integrate with one another.

If that's true, the internal integrations are the vendor's problem and your matrix only covers the external world. If it isn't — if the "suite" is three acquisitions wearing a shared login — then every internal module boundary is another interface you're going to build and maintain, except you won't have budgeted for it because it looked like one product on the quote.

This is worth a demonstration, not an assertion. Ask them to show one patient record moving through registration, clinical documentation, and billing, and watch for the seams: does a demographic change in one module appear in the others immediately, or does someone mention a nightly sync? Is there one patient identifier or a cross-reference table? The answer to "is this one system" is visible in about ten minutes if you know to look.

---

Next: Federating a Nation's Health Record — what changes when the same problems are posed across 340 million people. Previous: The 800-Line Requirements Worksheet.

The policy companion: The National Health Record a Republic Can Actually Build.