PatientFlow

A PatientFlow is the patient-facing browser flow in Connect. Your backend creates it, receives a URL, and sends the patient there. The patient authorizes access to one or more portals, then returns to your app.

Every PatientFlow belongs to one Patient. A Patient can have many PatientFlows over time because people reconnect, add new sources, or retry failed attempts.

Why PatientFlows Exist

OAuth is not a single API call. It includes a browser redirect, portal login, consent, code exchange, token storage, and a return to your product. A PatientFlow gives that whole flow one durable object with a pf_* public id.

That object lets your app answer practical questions:

• Is the link still usable?
• Did the patient finish the hosted flow?
• Which source did the patient try to connect?
• Did authorization succeed, fail, expire, or later lose refresh access?

The exact fields live in Initialize a Connect PatientFlow and the usage pages for Picker Mode and Direct Mode.

Lifecycle

open -> complete
open -> expired

open means the patient-facing URL is still valid. complete means the patient finished the browser flow. expired means the URL can no longer be used.

A PatientFlow can be complete even if authorization failed. The PatientFlow tracks the browser flow. The connection inside the PatientFlow tracks the authorization result.

Picker Mode

In Picker Mode, the PatientFlow URL opens a Medblocks-hosted search flow. The patient searches for a hospital, payer, or portal, selects the source, signs in, grants access, and lands on a completion screen.

Picker mode is best when you want to ship quickly or do not want to build source search UI yourself.

Direct Mode

In Direct Mode, your app chooses the source before creating the PatientFlow. The PatientFlow URL sends the patient straight to that portal’s login.

Direct mode is best when source choice belongs in your product, such as trial matching, intake, care navigation, or referral workflows.

Connections Inside A PatientFlow

Each authorization attempt creates connection state inside the PatientFlow. A connection can be active, failed, expired, or refresh failed.

Active means authorization succeeded and records can flow. Failed means the patient or portal returned an error. Refresh failed means access worked before, but the refresh token stopped working later and the patient needs to reconnect.

Background Pull

The PatientFlow ends when the patient finishes the browser flow. Record retrieval continues after that. Medblocks pulls records in the background, refreshes access before tokens expire, and tracks pull progress in the dashboard.

That separation keeps your app responsive. You can show “connected” after authorization, while operational users monitor record availability and exports separately.

Webhooks

Instead of polling, subscribe to the patient_flow.completed event so your backend is notified the moment a PatientFlow finishes. See Webhooks for the model and Webhooks Quickstart for a working receiver.

Related Articles

• Connect for the full product flow.
• Authorization for OAuth, PKCE, code exchange, and token refresh.
• Picker Mode for hosted source search.
• Direct Mode for your own source search UI.
• After Connection for what to do when the patient returns.