Patient session
How your app lets a patient connect their records, and how you track it.
Until recently, a patient couldn’t simply hand their medical records to an app like the one you are building. Reaching their data meant signing a contract with each health system and building a separate integration for every one. US ONC g(10) regulation changed that. ONC’s information blocking rules now require EHRs to let a patient pull their own records from a single link, and CMS’s patient access rules extend the same to health insurers. So a patient using your app can authorize you to read their records directly, by logging in to their hospital’s patient portal, like Epic MyChart, and approving access. We discuss this in more detail in Our approach.
A patient session is how your app does that for one patient.
What happens in your app
When a patient in your app chooses to connect their records, a patient session carries them through it.
- Your server starts a session and gets back a redirect URL.
- Your app redirects the patient to that URL.
- The patient logs in to their hospital’s portal and approves access for your app. Medblocks under the hood completes the OAuth handshake and fetches the access token. You can take a deeper look at how we do it in Authorization.
- The patient comes back to your app.
- Medblocks begins pulling their records in the background using the access token we got from the EHR.
The one part that changes is where the patient picks their hospital. You can let Medblocks host connection search on the page you send them to, or build it into your own UI and send the patient straight to the hospital they chose. Either way the rest of the flow is the same, and Create a patient session covers both.
Every patient session is uniquely identified by patient session ID. You keep it and use it later to check how the session went.
Checking how it went
Two things tell you what happened, and they answer different questions.
The session tells you whether the patient finished the flow.
open. The link is still live.complete. The patient finished and came back.expired. The link aged out, so you start a new session.
The connection tells you whether a hospital actually connected, which is what decides whether records flow. A session can finish with no connection, for example if the patient changed their mind at the portal, so the connection is the status you act on.
active. Connected, and records are on the way.failed. The attempt did not go through.refresh_failed. It worked before, but access lapsed and the patient needs to reconnect.
After connection shows how to read both in code.
One patient, many sessions
A patient is not limited to one session. They reconnect when access lapses, add another hospital later, or retry after a failed attempt. Each is a new session for the same patient, so you can list a patient’s sessions to see their full history.