Overview
A step-by-step build guide for a complete patient-access integration.
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.
This section is a build guide. The pages that follow take you through a complete patient-access integration, server and client, one step at a time. Read them in order: each page starts from the thing the previous page produced. They assume you have been through the concepts, so the focus here is on building.
How it works
Your server starts a patient session and gets back a redirect URL. Your app sends the patient to it. The patient signs in to their hospital’s patient portal, such as MyChart, and approves access for your app. Medblocks handles the secure authorization through SMART on FHIR behind the scenes and sends the patient back. Your server then reads the result before your UI shows them connected.
You can bring the patient through two ways.
| Approach | When to use | What happens |
|---|---|---|
| Medblocks-hosted page | You want Medblocks to host the page where the patient searches for and picks their facility. | The patient finds their facility, signs in to that facility’s patient portal to approve access, and returns to your app. |
| Your own UI | You want to build the facility search inside your own app. | The patient picks a facility in your UI, signs in to that facility’s patient portal to approve access, and returns to your app. |
You can use both in the same product.
What you’ll build
The build follows these pages in order. By the end you will have brought a patient from a button in your app to records flowing in.
- Find connections. Look up the hospital or clinic the patient uses.
- Create patients. Give each patient a stable
patient_id, or let the session create one. - Create a patient session. Start the session and get back the
urlwhere the patient approves access. - Handle the return. Read who came back on your
return_url. - After connection. React to the result and to events.
- Get the data. Pull the records into your systems.
Before you start
You need two things. Create an API key in your workspace, and install the SDK and create the client. The Quickstart covers both in a minute.