Patient Portal Experience

The patient portal is the primary interface for patients to manage their healthcare. This guide covers every feature patients interact with, designed to help support teams answer patient questions confidently.

Accessing the Portal

Patients access the portal through their organization's custom URL. After logging in, the system identifies the patient's record and loads their personalized portal experience.

First-Time Users

When a patient logs in for the first time without an existing patient record, they see a welcome screen with:

• A greeting message: "Welcome to Your Patient Portal"
• A prompt to create their patient profile via the "Create Your Profile" button
• A "Refresh to check" link for patients who believe they already have an account

Returning Users

Returning patients land on the Portal Home page, which displays a personalized greeting (e.g., "Good morning, Sarah") along with a summary dashboard of their healthcare activity.

Portal Navigation

The portal uses a left-side navigation drawer with the following sections:

Menu Item	Description
Home	Dashboard with tasks, messages, appointments, and service requests
Appointments	View upcoming and past appointments
Messages	Send and receive messages with care team
Requests	Submit service requests and view request status
Care Team	View assigned healthcare providers
Profile	View and edit patient demographics
Dependents	Manage family members and dependents
Uploads	Upload and view medical documents
Reports	Access medical reports
Billing	View billing information and payment history
User	Manage user account settings and notification preferences

The navigation also includes:

• Help button (when contact information is configured)
• Log Out button

At the top of the navigation drawer, the organization's logo is displayed along with the current patient's name and avatar. Clicking the patient name reveals a dropdown to switch between patients (for users managing dependents).

note

Some menu sections may not appear if the organization has disabled them. Section visibility is controlled by the organization's portal configuration.

Portal Home (Dashboard)

The home page provides a consolidated view of a patient's healthcare activity, organized in a two-column layout.

Left Column

Tasks

Displays actionable items assigned to the patient. Each task shows:

• Checkbox to mark completion
• Task title (with a document icon for form-based tasks)
• Description of what needs to be done
• Due date with overdue indicators when applicable
• Priority level (color-coded chip)
• Action button: "Complete Form" for form tasks, or "Details" for general tasks

Tasks that require form completion show a special "Complete Form" button that opens the associated questionnaire.

Recent Messages

Shows the most recent conversations with the care team in a compact view, allowing patients to quickly see new communications without navigating to the full Messages page.

Right Column

Appointments

Displays upcoming appointments with key details:

• Provider name
• Appointment type (virtual with video icon, or in-person with location icon)
• Date and time
• Status chip (e.g., confirmed, pending)

An appointment detail dialog opens when a patient clicks on any appointment, showing full information and actions like rescheduling or cancellation (when permitted).

Service Requests

Shows active service requests submitted by the patient, including:

• Request type with icon
• Current status
• Submission date

Workflow Recovery

If a patient has an incomplete registration or workflow, a recovery banner appears at the top of the home page. This allows patients to resume where they left off without losing any previously entered information.

Empty State (New Patients)

New patients who have just completed registration see action cards instead of the regular dashboard. These cards guide patients to take their first actions:

• Request an appointment
• Send a message to the care team
• Submit a service request

Each card includes an icon, title, description, and an action link.

Sending and Receiving Messages

The Messages page provides a full messaging interface for secure communication with the care team.

Message List (Left Panel)

• Search bar to filter messages by keyword
• New message button (+ icon) to start a conversation
• Conversation list showing:
  • Sender avatar with initials
  • Sender name
  • Message category
  • Subject line
  • Message preview (HTML stripped)
  • Date and time

Message Detail (Right Panel)

When a conversation is selected, the right panel shows:

• Full message thread with all replies
• Sender information and timestamps
• Message content (supports rich text)
• Reply input area

Starting a New Message

Patients can initiate new conversations by clicking the + button in the messages header. This opens a compose view where they can:

1. Select a recipient from their care team
2. Choose a message category
3. Enter a subject line
4. Write the message body
5. Send the message

Message States

State	What the Patient Sees
Loading	Spinner with "Loading messages..." text
Error	Error icon with "Failed to load messages" and a Retry button
Empty	Email icon with "No messages yet" and a "Start Conversation" button
No search results	Magnifying glass icon with "No messages found for [query]"

Managing Appointments

The Appointments page provides a dedicated dashboard for viewing and managing all appointments.

Quick Stats

Three summary cards display at the top:

• Upcoming: Count of future appointments
• This Month: Count of appointments in the current month
• Past: Count of completed appointments

Appointment Tabs

Appointments are organized into two tabs:

Upcoming Tab

Shows all future appointments in card format with:

• Provider name and specialty
• Date, time, and duration
• Appointment type (virtual/in-person)
• Status indicator
• Actions (view details, reschedule, cancel)

A Refresh button allows patients to manually update the appointment list.

Past Tab

Displays completed appointments with the same information format, useful for patients who need to reference previous visits.

Appointment Details

Clicking any appointment opens a detail dialog showing:

• Full provider information
• Appointment date, time, and duration
• Location or virtual visit link
• Appointment status
• Any associated notes or instructions

Rescheduling and Cancellation

When permitted by the organization:

• Rescheduling: Opens a dialog to select a new date and time from available slots
• Cancellation: Opens a confirmation dialog before cancelling the appointment

Switching Between Patients

Patients who manage dependents can switch between patient records directly from the navigation drawer.

How to Switch

1. Click on the patient name at the top of the navigation drawer
2. A dropdown menu appears showing all linked patients
3. Click on a different patient's name to switch to their record
4. The portal reloads with the selected patient's data

What Changes When Switching

When switching between patients, the entire portal context updates:

• Dashboard shows the selected patient's tasks, messages, and appointments
• Appointments page shows the selected patient's schedule
• Messages shows conversations for the selected patient
• Uploads shows documents for the selected patient
• Profile shows the selected patient's demographics

Adding a Dependent from the Switcher

The patient switcher also includes an "Add Dependent" option at the bottom of the dropdown list. Clicking this opens the dependent registration dialog directly, without navigating to the Dependents page.

Managing Dependents

The Dependents page allows patients to register and manage family members who share their portal login.

Viewing Dependents

The page displays dependent cards in a grid layout, each showing:

• Avatar with the dependent's initials
• Name and relationship type (e.g., Child, Spouse, Parent)
• Three-dot menu with options:
  • View Profile
  • Additional management options

Adding a New Dependent

1. Click the "Add Dependent" button at the top of the page
2. Select the relationship type
3. Complete the registration workflow for the dependent
4. The system creates a linked patient record

The dependent registration uses the same workflow as primary patient registration, with these differences:

• Account creation is skipped (dependents share the primary patient's login)
• Completion redirects back to the dependents list instead of the portal home
• The workflow respects all instance-specific steps (demographics, forms, documents, payments)

Dependent Registration Flow

The registration flow for dependents follows the same configurable steps as primary registration:

1. Demographics - Enter the dependent's personal information
2. Custom Forms - Complete any required questionnaires (if configured)
3. Document Upload - Upload required documents like ID or insurance cards (if configured)
4. Appointment Scheduling - Book an initial appointment (if configured)
5. Payment - Complete any required payments (if configured)

If a patient leaves during registration and returns later, the system preserves their progress and allows them to resume from where they stopped. This includes returning from external payment processors like Stripe.

Switching to a Dependent's Record

From the Dependents page, patients can:

• View Profile: Navigate to the dependent's patient profile
• Switch Context: Use the patient switcher to manage the dependent's portal (appointments, messages, uploads, etc.)

Uploading Files

The Uploads page allows patients to share medical documents, images, and other files with their care team.

Upload Interface

The page features:

• "Upload File" button in the header to trigger file selection
• Drag-and-drop zone for easy file uploading
• File list showing all previously uploaded documents

Uploading a File

1. Click "Upload File" or drag files into the drop zone
2. Select one or more files from your device
3. Files are uploaded automatically
4. A confirmation appears when the upload completes

Viewing Uploaded Files

Uploaded files are listed with:

• File name and type
• Upload date
• File size
• Download option

A "Download All" button appears when multiple files exist, allowing patients to download all their documents at once.

File States

State	What the Patient Sees
Loading	Spinner with "Loading files..."
No files	Document icon with "No files uploaded yet" message
No patient selected	Upload icon with "No patient selected" message

Viewing Care Team

The Care Team page shows all healthcare providers assigned to the patient.

Summary Card

At the top of the page, a summary card displays:

• Total Care Team Members count
• Primary Care Provider name (if designated)

Provider List

Each care team member is displayed as a card with:

• Provider name and credentials
• Role/specialty
• Contact information
• Avatar or photo

A search bar allows patients to filter providers by name when the care team is large.

Empty State

If no providers are assigned, a message indicates "No care team members found."

Profile Management

Patient Profile

The Profile page (/portal/:id/patient) shows the patient's demographic information in a read-only format, pulled from their FHIR Patient resource.

User Profile

The User page (/portal/:id/profile) allows patients to manage their account settings:

Editable Fields

• Name
• Email address
• Phone number
• Profile photo (with upload capability)

Notification Settings

A "Notification Settings" button opens a dialog where patients can configure how they receive notifications (email, SMS, push notifications) for different event types.

Saving Changes

Click "Save" to persist any profile changes. Error messages appear if the save fails, with clear descriptions of what went wrong.

Service Requests

The Requests page allows patients to submit and track healthcare service requests.

Submitting a Request

1. Click the "New" button on the Requests page
2. Select the type of request
3. Complete any required forms or information
4. Submit the request

Tracking Requests

Each request shows:

• Request type with icon
• Current status (pending, in progress, completed)
• Submission date
• Associated details

Billing

The Billing page provides patients with access to their billing information and payment history.

Reports

The Reports page allows patients to access medical reports and test results shared by their care team.

Help and Support

Patients can access help in two ways:

1. Help button in the navigation footer - Opens a dialog displaying the organization's contact information
2. Contact information displayed when configured by the organization

Common Patient Questions

"I can't see my appointments"

• Verify the patient is viewing the correct patient record (check the patient switcher)
• Appointments may take a moment to load; try the Refresh button
• The organization may have disabled the Appointments section

"How do I add a family member?"

1. Click the patient name in the navigation drawer
2. Select "Add Dependent" from the dropdown
3. Or navigate to the Dependents page and click "Add Dependent"
4. Complete the registration form for the family member

"I started registering a dependent but didn't finish"

The system saves progress automatically. When the patient returns:

• A workflow recovery banner may appear on the home page
• They can navigate back to Dependents and resume registration
• Previously entered information is preserved

"How do I switch to my child's/dependent's record?"

1. Click on the patient name at the top of the left navigation
2. Select the dependent's name from the dropdown list
3. The entire portal will update to show the dependent's information

"How do I send a message to my doctor?"

1. Navigate to Messages in the left navigation
2. Click the + button to start a new conversation
3. Select the recipient, category, and subject
4. Type the message and send

"How do I upload a document?"

1. Navigate to Uploads in the left navigation
2. Click "Upload File" or drag files into the upload area
3. Wait for the upload to complete
4. The file will appear in the list below

"I can't see some menu items"

Not all portal sections are enabled for every organization. If a section is missing, it has been disabled by the organization's configuration. Contact your healthcare provider for more information.

---

Last updated: March 2025