Medblocks-hosted page

Once you have a patient_id, start the browser journey that lets the patient approve access. This is the simplest way to connect a patient. Your app starts a patient session, sends the patient to the returned url, and lets Medblocks render the page where the patient finds their hospital or clinic. After the patient chooses a connection, they sign in to that patient portal and approve access for your app. They return to the return_url you set.

Start the session

Use this page when you want the patient to choose their connection after they leave your app. Your server starts the session with the patient’s ID and a return_url, and Medblocks returns a url for the patient. If you already know likely connections, pass them as recommended_connection_ids so they appear first.

If your app already has the exact connection the patient chose, use your own UI instead. That path sends the patient straight to that 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. The browser fetches that route and redirects the patient to the url it returns.

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

export async function initPatientSession(input: { patientId: string }) {
  const session = await mb.patientSession.init({
    patient_id: input.patientId,
    return_url: "https://app.example.com/connected",
    return_button_label: "Back to Acme Health",
  });

  return { url: session.url };
}

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

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

Return button

The hosted page ends on a Medblocks completion screen. At the bottom of that screen, Medblocks shows a button that sends the patient back to your app.

• return_url is the destination for that button.
• return_button_label is the button text the patient sees.

Use product-specific wording. Back to Acme Health, Continue, or Return to intake read better than a generic label.

When the patient taps the button, Medblocks redirects to your return_url with the patient ID and the patient session ID.

https://app.example.com/connected?patient_id=user_42&patient_session_id=ps_...

Recommended connections

Pass recommended_connection_ids when you already have a good guess at which facilities the patient uses. Those connections appear at the top of the hosted search, and the patient can still search for any other facility.

Omit recommended_connection_ids when you do not have suggested facilities to show first.

Next step

Common errors

Read the full envelope and code list in Errors.

See also