Patient Registration

The patient registration system provides a flexible, multi-step process that can be customized per instance. This allows organizations to collect the specific information they need while maintaining a consistent user experience.

Registration Workflow Builder

The upgraded workflow builder centralizes all registration and scheduling configuration in the admin portal.

Access

1. Sign in with an admin role.
2. Navigate to Settings > Registration.
3. The organization-level workflow opens by default. Instances can open their record and toggle Override Organization Settings to maintain a bespoke workflow.

Capabilities

• Drag-and-drop step order: Timeline view keeps required steps (Account, Demographics, Completion) pinned while letting you reposition optional steps.
• Add Step dialog: Insert new Custom Form, Service Request, Document Upload, Provider Availability Setup, Appointment Scheduling, or Payment steps without editing JSON.
• Per-step configuration cards: Each card exposes inline settings—form selection, instructions, SSN requirements, coverage validation, document guidance, etc.
• Scheduling configuration modal: Appointment steps now open a dedicated modal for booking window limits, calendar view modes, participant controls, and payment gating.
• Custom instructions: Rich text fields on every step surface contextual guidance to patients without redeploying the frontend.
• Automatic validation: The builder prevents duplicate system steps and enforces dependencies (for example, payments can only associate with service request if that step exists).

Organization vs Instance Overrides

• Organizations design a default workflow once.
• Each instance inherits that layout but can opt into overrides when regional or client-specific differences are required.
• Override toggles make the workflow read-only until enabled, preventing accidental divergence.

Registration Steps

The registration process consists of several configurable steps:

1. Account Creation (Required)

   • User creates their login credentials
   • Email verification
   • Basic account setup

2. Demographics (Required)

   • Collection of essential patient information
   • Name, date of birth, contact details
   • Address and location information
   • SSN collection for US residents (optional per instance)
   • Date of birth is captured with mobile-friendly Month/Day/Year dropdowns
   • Gender collection can be turned off with the Require Gender toggle (on by default)

3. Custom Forms (Optional)

   • Instance-specific forms can be added using FHIR Questionnaires
   • Forms appear as individual steps in the registration flow
   • Forms can be configured to pre-populate with existing patient data
   • Multiple forms can be added in a specified order

4. Medical Conditions (Optional)

   • Patients list their current medical conditions or health problems
   • Each condition captures a name and an optional onset date
   • Patients can confirm they have no conditions to report
   • Can be configured as a required or optional step
   • Responses are saved to the patient record as FHIR Condition resources

5. Service Request (Optional)

   • Request specific healthcare services during registration
   • Maps to FHIR ServiceRequest resources
   • Configurable service types per instance

6. Document Upload (Optional)

   • Allows patients to upload required documentation
   • Configurable instructions for document requirements
   • Support for multiple document types (ID, medical records, etc.)
   • Optional e-signature capability for documents

7. Provider Availability Setup (Optional)

   • Available for provider registration workflows
   • Allows practitioners to configure their recurring schedules
   • Set working hours, breaks, and availability patterns
   • See Managing Provider Availability for details

8. Appointment Scheduling (Optional)

   • Patients can book their initial appointment during registration
   • Integrates with the upgraded scheduling engine used by the portal
   • Supports streamlined or full calendar layouts, custom instructions, and optional pre-appointment forms
   • Default practitioners can be auto-added with the participant picker or hidden entirely from patients
   • Configurable booking window (min/max days out) and payment requirements

9. Payment (Optional)

   • Stripe integration for secure payment processing
   • Can be enabled/disabled per instance
   • Configurable payment requirements
   • Support for required and optional products
   • Custom payment instructions

10. Completion

• Displays success message with next steps
• Instance-specific completion instructions
• Links to patient portal

Dependent Registration

Registered patients can add family members and dependents to their account directly from the patient portal.

How It Works

1. Navigate to Patient Portal > Dependents
2. Click Add Dependent
3. Select the relationship type (child, spouse, parent, etc.)
4. Complete the registration form for the dependent
5. The dependent is linked to your account via a RelatedPerson resource

Key Features

• Streamlined Process: Uses the same registration workflow, skipping account creation since dependents share your login
• Relationship Tracking: FHIR-compliant RelatedPerson resources link patients together
• Patient Switching: Easily switch between managing your own care and your dependents' care in the portal
• Full Access: Dependents have complete patient records including appointments, documents, and care plans

Configuration

To enable dependent registration:

1. Ensure the registration workflow is configured for your instance
2. Navigate to Settings > Registration
3. Enable "Allow Dependent Registration"

Dependents inherit most registration steps from the main workflow, excluding:

• Account creation (they use the primary patient's login)
• Completion step (redirects back to dependents list)

Instance Customization

Instances can be customized in several ways to modify the registration experience:

Branding

• Custom logo and icon
• Background image
• Instance name and headline
• Patient-facing instance name (separate from internal name)
• Subtitle and call-to-action text
• Contact information display

Patient-Facing Instance Name

The patient-facing instance name allows you to display a custom name to patients during registration and throughout their experience, separate from your internal instance name. This feature provides:

• Enhanced Branding: Display your preferred name to patients
• White-labeling Support: Use different names for internal vs. patient-facing interfaces
• Consistent Experience: The patient-facing name appears across all patient interfaces
• Automatic Fallback: If no patient-facing name is set, the system uses the internal name

Configuration:

1. Navigate to Instances > [Your Instance] > Branding
2. Locate the "Patient-Facing Name" field
3. Enter your desired patient-facing name
4. Save the configuration

The patient-facing name will be displayed in:

• Registration form headers and titles
• Patient portal navigation
• Login page branding
• Document titles and footers
• Email communications

Registration Step Configuration

Each registration step can be individually configured:

Step	Configurable Options
Account	Email verification settings, password requirements
Demographics	SSN requirement, coverage area validation, Require Gender toggle
Custom Forms	Form selection, pre-population, required vs optional
Medical Conditions	Required step toggle
Service Request	Service types, form associations
Documents	Required documents, e-signature, upload instructions
Provider Availability	Location associations, default hours
Appointment	Service types, provider filters, required step toggle, scheduling options
Payment	Products, payment timing, default status
Completion	Custom instructions, redirect behavior

Appointment Scheduling Configuration

The scheduling modal that backs the appointment step exposes the features added in the latest release:

• Required Step Toggle: Enable this option to make appointment scheduling mandatory during registration. When enabled, patients cannot skip the appointment step and must book an appointment before proceeding. This provides organization-wide policy enforcement for mandatory scheduling.
• View Modes: Choose Standard (multi-day grid) or Streamlined (single-day wizard) layouts per workflow.
• Participant Experience: Select default participants (multi-select) to attach practitioners to appointments automatically.
• Booking Window & Limits: Set min/max days out, honor organization-level guardrails automatically, and optionally require completion of a payment step before appointments can be confirmed.
• Service Filters: Lock a workflow to specific healthcare services or allow open selection.
• Custom Instructions & Forms: Attach pre-appointment questionnaires or contextual copy directly from the modal.

Mandatory Scheduling vs Service-Level Requirements

There are two mechanisms for controlling appointment requirements:

The Required Step toggle (workflow-level) makes the entire appointment step mandatory for all patients going through the registration workflow. This is configured in the workflow builder on the appointment step card.

The Appointment Required setting (service-level) is configured on individual HealthcareService resources.

When the workflow includes a Service Request step, the service the patient selects decides whether scheduling applies at all: a service with Appointment Required enabled always has to book an appointment before continuing (so payment cannot be reached without one), and a service without it skips scheduling entirely — the patient goes straight to the next applicable step, and returning from a later step does not reintroduce scheduling. The workflow-level Required Step toggle applies to workflows that schedule without a service selection.

Default Participants

Default participants ensure critical care team members are always attached to appointments created during registration:

• Configure from the Configure Options modal on the appointment card.
• Multiple participants are supported; all selected practitioners are added with accepted status in the Appointment resource.
• Patients see the final summary with the auto-populated care team.
• Combine with load-balancing rules on the Scheduling Settings page to distribute appointments fairly even when defaults are present.

Forms Configuration

• Add/remove custom forms (FHIR Questionnaires)
• Set form order in registration flow
• Configure form pre-population with patient data
• Set form completion requirements (required/optional)

Document Requirements

• Configure required documents
• Set document upload instructions
• Enable e-signature requirements
• Customize document descriptions

Payment Settings

• Enable/disable payment requirement
• Configure default payment status
• Set default and optional products (via Stripe)
• Custom payment instructions
• Appointment status control for unpaid registrations

Scheduling Configuration

When appointment scheduling is enabled during registration:

• Workflow-specific rules: Booking windows, participant behavior, and required payment can be set per workflow without affecting portal scheduling.
• Service Type Filtering: Limit available appointment types and associate pre-appointment forms.
• Provider Filtering: Restrict to specific providers, roles, or care teams—or rely on the upgraded load balancer to auto-assign.
• Calendar View Modes: Standard (multi-view) or Streamlined (single-day) experiences can be toggled with a dropdown.
• Custom Instructions: Add guidance text for patients plus optional "reason for visit" capture.

Additional Settings

• Custom Terms of Service
• Custom Privacy Policy
• SSN requirement toggle for US residents
• Custom completion instructions
• Instance-specific contact information
• Custom domain configuration
• Email sender configuration
• Coverage area validation

Email Confirmation

Administrators control whether patients must verify their email address during registration:

1. Sign in with an admin role and open the Organization settings page.
2. In the Registration Settings card, toggle Require Email Confirmation.

When enabled, patients must verify their email address with a one-time code before their account is created. When disabled, accounts are confirmed automatically and patients are signed in without entering a code.

Responsive Design

The registration workflow is fully responsive and optimized for:

• Desktop: Full-featured experience with multi-column layouts
• Tablet: Adapted layouts with touch-friendly controls
• Mobile: Single-column design optimized for small screens

Data Created During Registration

Registration creates the following records:

Resource	Purpose
Patient	Core patient demographics and identifiers
RelatedPerson	Links dependents to primary patients
QuestionnaireResponse	Captures custom form responses
Condition	Records medical conditions reported during registration
DocumentReference	Stores uploaded documents
ServiceRequest	Records requested services
Appointment	Scheduled appointments during registration
Coverage	Coverage information (if collected)

Best Practices

Workflow Design

• Keep required steps to a minimum for better conversion
• Use custom forms sparingly—only collect essential information
• Enable appointment scheduling to reduce post-registration friction
• Provide clear completion instructions

Testing

• Test the full registration flow before launch
• Verify email delivery and verification
• Test on mobile devices
• Confirm form pre-population works correctly

Monitoring

• Track registration completion rates
• Monitor drop-off points in the workflow
• Review form completion times
• Address common support issues
• Re-test workflow overrides whenever the organization default changes
• Spot-check appointment bookings to confirm default participants and payment requirements behave as expected

Embedding the Registration Workflow

You can embed the patient registration workflow directly inside an existing website using an <iframe>, so patients never leave your site to register.

1. Whitelist your website's domain

For security, the registration form will only load inside an iframe on domains you have explicitly approved.

1. Sign in with an admin role and open Settings for the instance you want to embed.
2. Go to the Settings tab and find the Share & Embed section.
3. In Allowed Embed Domains, add each website domain that will host the iframe (for example https://www.yourclinic.com). Type the domain and press Enter to add it; add as many as you need.
4. Save the instance.

If a domain is not listed here, browsers will block the registration form from loading on that site.

2. Copy the embed code

In the same Share & Embed section, copy the Registration Embed Code. It looks like this:

<iframe src="https://yourinstance.example.com/register?embed=true" width="100%" height="800" frameborder="0" allow="camera; microphone"></iframe>

Paste it into the HTML of the page where you want registration to appear. Adjust the width and height to fit your layout.

3. Customize the embedded experience (optional)

The embed is controlled with URL parameters appended to the /register link. Combine them as needed.

Parameter	Default	Effect
embed	false	Set to true to turn on embed mode. Hides the background and renders the registration card full-screen so it fills the iframe.
showBackground	true standalone, false when embed=true	Set to false to hide the page background and make the card fill its container; set to true to keep the background even while embedded.
hideLogo	false	Set to true to hide the instance logo. Useful when your own page already shows your branding.
hideFooter	false	Set to true to hide the contact-information footer.

Example hiding the logo and footer:

<iframe src="https://yourinstance.example.com/register?embed=true&hideLogo=true&hideFooter=true" width="100%" height="800" frameborder="0" allow="camera; microphone"></iframe>

The allow="camera; microphone" attribute lets steps that need a camera or microphone (such as document capture) work inside the iframe. Leave it in place unless your workflow has no such steps.

Troubleshooting

Common Issues

Registration Not Loading

• Verify instance configuration is complete
• Check that the registration workflow has enabled steps
• Confirm the instance URL is correctly configured

Forms Not Displaying

• Ensure the Questionnaire exists and is active
• Verify form permissions for anonymous users
• Check that the form ID is correctly configured

Embedded Form Blocked or Blank

• Confirm the hosting site's domain is listed in Allowed Embed Domains (Settings → Share & Embed)
• Include the scheme in the domain (https://www.yourclinic.com, not www.yourclinic.com)
• Make sure the iframe src includes ?embed=true
• Check the browser console for a Content Security Policy / "frame-ancestors" error, which indicates the domain is not whitelisted

Payment Issues

• Verify Stripe integration is configured
• Check payment product settings
• Review Stripe dashboard for errors

Dependent Registration Errors

• Ensure user is logged in
• Verify primary patient record exists
• Check relationship type is valid

Related Documentation

• Portal Requests - Configure post-registration patient request workflows
• Instance Configuration
• Managing Provider Availability
• Healthcare Services

---

Last updated: August 2026