Medblocks-hosted page
The least-code way to connect a patient. Start a session, send them to the URL you get back, and let Medblocks render the page where they find their hospital and approve.
Open in
Show prompt text
You are an AI coding agent helping integrate Medblocks Patient Access into the codebase that is currently open. Treat the live Medblocks docs and generated API reference as the source of truth. If you are running inside a local repo that contains openapi/medblocks.json, read it too. Do not rely on endpoint names, SDK calls, response fields, or code snippets from memory. Before changing code, read the current docs directly. - Patient Access overview https://medblocks.com/docs/patient-access/overview - Find connections https://medblocks.com/docs/patient-access/find-connections - Create patients https://medblocks.com/docs/patient-access/create-patients - Create a patient session https://medblocks.com/docs/patient-access/create-patient-session - Medblocks-hosted page https://medblocks.com/docs/patient-access/create-patient-session/medblocks-hosted-page - Your own UI https://medblocks.com/docs/patient-access/create-patient-session/your-own-ui - Handle the return https://medblocks.com/docs/patient-access/handle-the-return - After connection https://medblocks.com/docs/patient-access/after-connection - Get the data https://medblocks.com/docs/patient-access/get-the-data - API conventions https://medblocks.com/docs/reference/conventions - API reference https://medblocks.com/docs/reference/api Use the page I copied this from as the immediate task context, then use the rest of the Build pages to understand the full flow. Work in this order. 1. Inspect this codebase first. Identify the app framework, server boundary, environment variable pattern, existing API client pattern, current patient or user identity model, logging style, and test runner. 2. Read the generated API reference before naming any route, field, enum, header, error code, or SDK method. If your tool has local filesystem access and this repo has openapi/medblocks.json, read that too. If the docs and reference disagree, stop and ask the user which source to follow. 3. Decide whether this app should use the Medblocks-hosted page, your own UI, or both. Ask the user if the answer is not obvious from the product. 4. Keep the Medblocks API key server-side. Never expose it through public environment variable prefixes, frontend bundles, browser logs, or client-side fetches. 5. Implement the smallest complete path for the selected page. Follow existing project conventions for file locations, naming, validation, errors, loading states, and tests. 6. After a patient returns from authorization, verify the result from the server using the latest documented Patient Access status flow. Do not trust query string values as the final source of truth. 7. Preserve Medblocks request IDs and documented error details in logs and server responses where safe. Avoid logging PHI unless this codebase already has an approved pattern. 8. Run the relevant type checks and tests before reporting done. If a live smoke test needs credentials the repo does not have, explain the exact manual smoke test steps. If any required detail is missing, ask concise questions before writing code. In a healthcare integration, a correct pause is better than an incorrect assumption.
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 };
}patient_idstringrequiredYour stable identifier for this patient.
patient_emailstringPatient email to store or update.
patient_namestringPatient display name to store or update.
recommended_connection_idsstring[]Connection IDs to show first on the Medblocks-hosted page. Mutually exclusive with connection_id.
return_urlstringrequiredURL to redirect after the patient session.
return_button_labelstringText shown on the patient-facing completion button.
metadataobjectAdditional metadata returned with the patient session.
AuthorizationBearer <token>requiredMedblocks API key for server-side requests.
VersionstringDate-pinned API version. If omitted, Medblocks uses the version pinned on your API key.
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;
}patient_idstringrequiredYour stable identifier for this patient.
patient_emailstringPatient email to store or update.
patient_namestringPatient display name to store or update.
recommended_connection_idsstring[]Connection IDs to show first on the Medblocks-hosted page. Mutually exclusive with connection_id.
return_urlstringrequiredURL to redirect after the patient session.
return_button_labelstringText shown on the patient-facing completion button.
metadataobjectAdditional metadata returned with the patient session.
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_urlis the destination for that button.return_button_labelis 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_...patient_idstringrequiredYour developer-supplied external patient id. Use this to look up the patient via GET /patients/{id}.
patient_session_idstringrequiredThe ps_* public id of the completed patient_session.
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
The patient lands on your return_url with patient_id and patient_session_id in the query string. Continue to Handle the return to read those params and show which facilities connected.
Common errors
| Code | Meaning |
|---|---|
invalid_api_key | The API key is missing, invalid, or expired. |
unsupported_api_version | The Version header is not supported. |
resource_not_found | A recommended connection ID does not exist or is not visible to your organization. |
bad_request | Request fields are missing, malformed, or mutually exclusive. |
Read the full envelope and code list in Errors.