Create a patient session
Pick who renders connection search. Let Medblocks host the page, or build it into your own UI.
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.
To pull a patient’s records, you first need them to sign in to their hospital’s patient portal, such as MyChart, and approve access for your app. That sign-in is the authorization step. There are two ways to put it in front of the patient. You can let Medblocks host the page, or build it into your own UI and send the patient straight to the hospital they chose.
Both end the same way. The patient runs through the same authorization, you get back the same patient session, and you read the same connection result. The only thing that differs is who renders connection search, where the patient finds and selects the hospital or clinic whose records you want to pull.
Medblocks-hosted page
Send the patient to a prebuilt page Medblocks hosts. They find their connection and approve there. The least code.
Your own UI
Build connection search into your own app with the SDK, then send the patient straight to their portal. Full control of UX and branding.
How to choose
The split comes down to three things, who renders connection search, how much control you have over how it looks and feels, and how much you build.
| Medblocks-hosted page | Your own UI | |
|---|---|---|
| Who renders connection search | Medblocks, on the page you redirect to | You, inside your app |
| UX and branding control | The page is themed to your brand, but the layout and copy are Medblocks’ | Full control. The search is part of your product |
| What you build | A redirect. Your server starts the session, then you send the patient to the url you get back | Search on top of the connection catalog, plus the redirect once the patient picks |
With the Medblocks-hosted page, your app does not need to know which connection the patient uses, and you build no search UI. The patient searches the catalog, picks a connection, and approves, all on the hosted page. That is the fastest way to launch.
With your own UI, you search the connection catalog yourself (see Find connections), show the results however you like, and pass the connection the patient picked into the session. The patient lands on their portal login directly, having never left your design.
Reach for the Medblocks-hosted page when you want the fastest launch and are happy to let Medblocks render connection search. Reach for your own UI when picking a connection is part of your product, like an intake or trial-matching flow where the choice carries its own context, or when you need full control of the experience.
You are not locked in. You can use both in the same product, for example offering your own search and falling back to the hosted page when a patient cannot find their hospital.