Evidence-Based Integration.

The documentation is a hypothesis

The first thing you learn integrating with an EMR is that the vendor's documentation, sample payloads, Postman collection and SDK are not four sources. They're one belief about the system, exported four ways. When one is wrong, the rest are wrong in the same place.

A small example. Two platforms, same FHIR standard, patient create. One rejects the write unless telecom.rank is set to 1. The other ignores rank entirely. The spec marks it optional, so neither is wrong — and FHIR gives a server a way to publish exactly that kind of constraint. Neither did. You find out by sending the request.

That isn't a war story. That's Tuesday. And it's why you can't design against the documentation: an architecture is only as sound as the model of the system under it, and if the model came from the vendor, its defects are now in your estimate.

So you reverse engineer first

Not when something breaks. Before the design.

Start from the vendor's payload, including the one that fails. Turn it into a stub you can change one field at a time. Check it against the three things that can disagree — the FHIR spec, the server's CapabilityStatement, and whatever service descriptor the platform exposes. The disagreements are the work list.

Then use the platform's own UI. Change one thing, GET it back, diff. The write path can't be out of date — assuming the sandbox tracks production, which you also check. Add and remove fields until required and optional are what you observed, not what the spec says.

No UI, or a sandbox that doesn't work? It happens. The loop still runs from the payload structure. It just converges slower.

The tooling is whatever it takes

By hand this is slow, and the knowledge ends up in one person's head. So we build something to run it — a console, a harness, a signing module with tests. It's different every time, and it isn't the point.

The point is that each probe gets cheap, and what gets recorded is the conclusion, not the request.

That's what AI actually changed here. It found nothing; every finding came from a request and a response. What it did was collapse the cost of the loop — stub variants, diffs, writing up each conclusion — from days to hours. So we run it on every uncertain field instead of the three we're most worried about.

What you keep: the register

Every operation gets a status.

Partial is the one that matters, and it isn't what it sounds like. Practitioner create returns 201. The record exists; you can read it back. It never appears in the dropdown clinicians actually pick from, and whatever makes a provider eligible for that list is undocumented — type, status, schedule, site, all candidates. Sometimes it's this. Sometimes it's a capability that's really three calls and the second has no API. Either way the request succeeded and the integration didn't, and pass/fail reporting has nowhere to put that, so it goes in the green column.

An entry holds more than a status. What the endpoint actually requires. What we send that the docs don't mention, and why — a generated signing key, because the sample ships a real-looking one that every provider would otherwise share. And the gaps: where the docs are absent, wrong, or misleading. One vendor misspelled the resource name in all thirteen of its extension URLs. It's in their spec and their live responses. You don't fix it. You match it.

Every status carries the date and environment it was observed in. Untested is called untested. Values and status codes, not adjectives. Dead ends stay written down so nobody pays to find them twice.

Whatever's left becomes a numbered question to the vendor with a reproduction case. That gets answered. "It doesn't seem to work" doesn't.

One file. Three copies drift, and drifted documentation is confidently wrong.

Take the register schema with you ↓

Why not wait for the vendor

We ask. It's the right thing to do, and it isn't a plan.

Fixes land in quarters. More than once the vendor's answer has been that their own developer would have to read the code — which tells you what the documentation was worth.

Support isn't uniformly bad; it's rationed. One platform had good engineers, but we had no UI access, so every question about real behaviour went through them, and responsive still means days. Another shipped a sandbox that never worked; we built our own from the payload structure so product work could continue.

Neither is negligence. It's the model. At most vendors the default tier is slow and the fast tier costs thousands, while the sandbox bills monthly — sometimes a year upfront. You pay to wait, and pay more not to. None of it is in the original estimate.

Reverse engineering is the third option. If you're bootstrapping, it's usually the only one that pencils.

Where this comes from

Not healthcare. Device protocols — where the spec was a starting hypothesis and the wire was the authority — and system test, where you don't record a result you didn't watch happen.

Applied to API integration it looks unusual. It shouldn't.

Your problem has already been solved. In a different industry.

What you get

A findings register: every operation, its status, the evidence, and where the documentation and the system disagree. A vendor ask list: the questions that have to be answered before the rest can be scoped, each with a reproduction case.

Both are yours. Hand them to your team, your vendor, or whoever comes next. A date built on observed behaviour is one you can defend.