Reference

Embedding the clinical-data UI

A patient’s clinical data — visits, procedures, diagnoses, prescription fills, and lab results — is available as an embeddable, server-rendered UI you can drop into your own product as an iframe. This is the recommended integration path for any surface that displays a patient’s clinical data to end users.

Why embed?

The per-table browse endpoints (POST /v0/visits/browse, /v0/diagnoses/browse, and friends — see Browsing tables) expose the raw clinical-data schemas, and those schemas change frequently as we expand claims coverage and add columns. Consumers that embed the iframe pick up every change automatically and never handle schema drift; consumers that marshal the raw browse rows themselves accept ongoing maintenance cost. Embedding also means you never forward your backend API key to an end-user browser — the embed token is scoped to a single patient and expires in an hour.

1. Mint an embed token

POST /v0/companies/{companyId}/projects/{projectId}/patients/{patientId}/clinical-data-embed-token (authenticated with your bearer token) accepts a { "parentOrigin": "https://your-approved-host.example" } body and returns an EmbedTokenResponse { token }. The token is a stateless, authenticated-encrypted string locked to that one patient: the embed forces the company/project/patient filters server-side on every render, so a holder can never widen past the patient the token was minted for. Reads are attributed to the minting user. parentOrigin is the exact origin of the page that frames the iframe: https://host[:port] with no path, query, fragment, credentials or wildcard, on the deployment’s approved browser-origin allowlist, or the mint is answered with 400. It binds framing, and the browse-state messages below, to that exact origin.

Deprecated: omitting the body or parentOrigin still mints a token, framed by any page and posting its messages to any parent (legacy wildcard). A later release will require parentOrigin and answer a mint without it with 400, so send it now.

2. Load the iframe

Embed iframe

html

<iframe
  src="https://api.hermeshealth.ai/ui/clinical-data/embed?token=<token>"
  style="border:0;width:100%;height:100%"
  title="Clinical Data"></iframe>

The embed routes are token-authed only — no session cookie — so the token may be handed to the end user, but only the parentOrigin sealed into it may frame the iframe. Optional query parameters:

tab — which entity tab to open first (visits | procedures | diagnoses | prescription-fills | lab-results; defaults to visits).
panel — an opaque browse-state blob to restore filters / sort / page (see below).
map — expanded (default) or collapsed for the facility map card’s initial state.

3. Persist browse state (optional)

A sandboxed cross-origin iframe can’t write the host page’s URL, so the embed postMessages its current browse state to the parent window on every change: a { type: "hermes:clinical-data", entity, tab, panel } message addressed only to the exact approved parentOrigin sealed into the token. A token minted without one (deprecated) posts to the wildcard target. Persist the panel value (e.g. onto your own URL) and pass it back as the panel query parameter to reload the iframe into the same view.

Token lifetime

Clinical-data embed tokens expire one hour after minting, and every embed request re-resolves the minting user and re-checks they can still see the token’s patient — so revoking a user’s access invalidates their outstanding tokens immediately. Mint a fresh token each time you render the page hosting the iframe rather than caching tokens.