After connection

After your return page has parsed patient_id and patient_session_id, confirm the outcome on your server. A patient session finishing is not the same as a connection going active, and a connection going active is not the same as records being ready. This page covers all three, the authoritative reads on your server and the events that save you from polling for them.

Read the session

Call mb.patientSession.retrieve(id) on your server with the patient_session_id you read from the return. It gives you the session and its connections, one per facility the patient tried in that session.

import { mb } from "./medblocks";

const session = await mb.patientSession.retrieve(patientSessionId);

const active = (session.connections ?? []).filter((c) => c.status === "active");
const connected = active.length > 0;

A session can be complete and still have connected nothing, for example if the patient changed their mind at the portal. So the session lifecycle answers whether the patient finished, and the connection status answers whether records flow. The real success signal is a connection going active, not the session being complete. Act on the connection.

// session.status is the patient's progress, not the result.
// connections[].status decides whether records flow.
const failed = (session.connections ?? []).filter((c) => c.status === "failed");
const lapsed = (session.connections ?? []).filter((c) => c.status === "refresh_failed");

A refresh_failed connection worked before but its access lapsed, so prompt the patient to reconnect. Authorization explains why access lapses.

Read the patient’s connections

A session shows one trip. To see everything a patient has connected across every session, read the patient. mb.patients.retrieve(id) returns the patient with a connections array, each entry carrying a connection_id and a status, including failed attempts so you can surface them.

import { mb } from "./medblocks";

const patient = await mb.patients.retrieve("user_42");
const live = patient.connections.filter((c) => c.status === "active");

Those entries name the facility by ID, not by its display name or logo. The getConnections helper does that lookup for you and hands back fully rendered facilities, ready to drop into a UI. It skips failed connections, since they carry no data.

import { mb } from "./medblocks";

const facilities = await mb.patients.getConnections("user_42", { hydrate: true });

for (const facility of facilities) {
  console.log(facility.name, facility.logo_url, facility.fhir_base_url);
}

A patient’s session history

A patient is not limited to one session. They reconnect when access lapses, add another hospital later, or retry after a failed attempt. mb.patients.listPatientSessions(id) lists every session a patient has had, most recent first, which is what you want for a “past connections” view or a support screen.

import { mb } from "./medblocks";

const page = await mb.patients.listPatientSessions("user_42", { limit: 50 });

for (const session of page.data) {
  console.log(session.id, session.status);
}

The result is cursor-paginated. Await it for the first page, or iterate it to walk them all.

Listen to events

Reading the session tells you where things stand at one moment. But records arrive in the background after the patient has moved on, and access can lapse weeks later, so polling for either is wasteful and slow. Subscribe to events instead. Medblocks posts to your server the moment something settles.

Four events matter here.

• patient_session.completed. The patient finished a session. Update your connected UI and kick off whatever should happen next.
• records.sync.completed. A background pull settled and new records are ready to read. Trigger downstream processing here rather than guessing when the data has landed.
• records.sync.failed. A background pull errored. Surface it or page your on-call team.
• connection.token_refresh_failed. A connection’s access lapsed. Prompt the patient to reconnect to resume the pull.

The full payload for each is in the event catalog, and the webhooks quickstart walks you through a receiver that verifies signatures so you can trust what arrives. Build the receiver there, then handle these four events.

Common errors

Read the full envelope and code list in Errors.

See also