Your own UI

After the patient has chosen a connection in your UI, start a session for that specific facility. Build connection search into your own app wherever it fits, an intake form, a trial-matching flow, an account settings page, or a dedicated search screen. The patient chooses a connection, you start a patient session for that connection, and they land directly on that facility’s patient portal to sign in. Reach for this when choosing a facility is part of your product experience, or when you want full control of the look and feel.

The rest of the flow is unchanged. The patient signs in to their hospital’s patient portal, approves access for your app through authorization, and returns to you. Medblocks then pulls their records in the background.

Find the connection

The patient chooses a connection in your UI, and you keep its connection ID, which looks like fhirsrc_01J9YR9N3X4VZ6P2K5RH7M3LMP. That ID is what you pass into the session below. Find connections covers searching the catalog and rendering the results, so this page picks up once the patient has chosen.

Start the session for that connection

When the patient chooses a connection, start a session for it. Your server calls mb.patientSession.init with the patient’s ID, the connection’s connection_id, and a return_url, and gets back a url. Your browser code then redirects the patient to that url, which sends them straight to the facility’s patient portal. Your API key is a secret that lives only on your server, so the browser calls a route on your server and never the Medblocks API directly.

Pass the connection_id of the connection the patient chose. That tells Medblocks which facility’s patient portal to send them to.

import { mb } from "../medblocks";

export async function startSession(input: {
  patientId: string;
  connectionId: string;
}) {
  const session = await mb.patientSession.init({
    patient_id: input.patientId,
    connection_id: input.connectionId,
    return_url: "https://app.example.com/connected",
  });

  return { url: session.url };
}

async function startSession(connection: { id: string; name: string }) {
  const response = await fetch("/api/patient-sessions", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      patientId: currentPatientId,
      connectionId: connection.id,
    }),
  });

  const { url } = await response.json();
  window.location.href = url;
}

Handle success and failure

When your app sends the patient straight to one connection, the return_url includes success or failure details for that connection. Every return carries the patient ID (patient_id), the patient session ID (patient_session_id), and a success flag. On success the URL also carries the connection_id that connected. On failure it carries an error code and an error_description instead.

On success, the patient lands back on your app with the facility connected.

https://app.example.com/connected?patient_id=user_42&patient_session_id=ps_...&success=true&connection_id=fhirsrc_...

When the patient cancels or the portal rejects the attempt, the URL carries success=false with the error code and description, so you can show a retry path.

https://app.example.com/connected?patient_id=user_42&patient_session_id=ps_...&success=false&error=user_denied&error_description=Patient+canceled+the+connection

Common errors

Read the full envelope and code list in Errors.

See also