Designing APIs Hospitals Can Actually Build On

Most healthcare software promises an API, and most of those APIs are a disappointment when a hospital's own team finally tries to build on them. The endpoints exist but the documentation lags the behaviour. Authentication is a bespoke scheme nobody else uses. There is no way to be notified when something changes, so integrations resort to polling every few minutes and hoping. The gap between "we have an API" and "you can actually build on our API" is enormous, and hospitals only discover which side of it a vendor sits on after they have signed. Designing APIs that hospitals can genuinely build on is a discipline, and it is worth being explicit about what it takes.

The difference between an API and a platform

Having endpoints is table stakes. Being buildable is a higher bar, and it is defined by whether an integrator who has never met your team can succeed from the documentation alone. That means a few things have to be true at once:

• Predictable, resource-oriented REST, so once someone learns one endpoint they can guess the shape of the next.
• Consistent authentication using an approach integrators already know, rather than a scheme invented in-house.
• Clear versioning, so an upgrade on the vendor side does not silently break a hospital's working integration.
• Honest, current documentation that matches what the API actually returns, including the error cases.

An API is only as good as the worst surprise it springs on the developer at 2 a.m. during a go-live.

The test is simple and unforgiving: can a hospital's IT team, or a third-party integrator, build something real without a single support call? If the answer is no, it is not a platform. It is a set of endpoints with a marketing label.

Stop polling, start listening

The single biggest quality-of-life difference between a mediocre API and a good one is webhooks. Without them, any integration that needs to react to a change has to poll - ask "has anything happened yet?" over and over, most of the time to be told no. Polling is wasteful, it is slow, and it scales badly as the number of integrations grows.

Webhooks invert the model. Instead of the hospital's system asking repeatedly, Kōami's platform calls the hospital's system the moment something relevant happens. The events that matter in a hospital map naturally onto this:

• A patient is admitted, discharged or transferred, so the pharmacy or billing system reacts immediately to the ADT event.
• A lab result is finalised, so an external portal updates without a five-minute delay.
• An inventory item crosses its reorder threshold, so procurement is notified in real time.
• A credential is approaching expiry, so an external compliance dashboard picks it up.

Real-time delivery is not a luxury feature. In a hospital, the difference between "now" and "in five minutes" is sometimes the difference between a safe workflow and a dangerous one.

Build webhooks that survive the real world

Webhooks are easy to demo and hard to do well, because the real world is unreliable. The receiving system will occasionally be down, slow, or briefly unreachable, and a naive webhook simply loses the event. A serious implementation plans for failure:

• Retries with backoff, so a momentary outage on the hospital's side does not drop the event permanently.
• Signed payloads, so the receiver can verify the call genuinely came from Kōami and not from an impostor.
• Idempotency keys, so a retried delivery does not cause the same admission to be processed twice.
• A replay or catch-up mechanism, so a system that was down for an hour can recover the events it missed.

Skip these and you have a webhook that works in the demo and fails in production. The unglamorous reliability engineering is exactly where "we support webhooks" becomes "you can depend on our webhooks."

Design for least privilege

An open API in healthcare is also an expanded surface for accessing sensitive data, and that has to be treated with respect rather than bolted-on caution. Buildable does not mean wide open. The right posture is granular scopes, so an integration that only needs to read inventory levels cannot reach patient records, and every credential is scoped to the least it needs to do its job. Access should be auditable, so a hospital can see which integration read what and when. This is a capability question, not a certification claim: the point is to give hospitals the controls to grant narrow, revocable, observable access rather than handing out keys to everything.

Documentation is part of the product

The last mile of a buildable API is the part vendors most often neglect: the documentation, the sandbox, and the examples. An integrator should be able to read the reference, try a call against a test environment that behaves like production, see a worked example for the common flows, and understand the error responses without reverse-engineering them. Kōami treats this material as part of the product rather than an afterthought, because an undocumented capability is, for practical purposes, a capability that does not exist.

Hospitals are not asking for a magic integration that reads their minds. They are asking for the plumbing to connect the systems they already run - the LIS, the third-party portal, the analytics stack - without a services contract for every small change. That is what open, well-versioned REST APIs and reliable webhooks provide: the ability to build, to react in real time, and to do it safely with access scoped to exactly what each integration needs. The measure of success is quiet. A hospital's own team ships something useful, on their own, and never needs to call you to do it.