Skip to main content

Provider Patient Access API

The Provider Patient Access API enables individual patients to securely access their own health records from healthcare provider systems. This FHIR R4-compliant API supports patient-facing applications and follows SMART on FHIR specifications to ensure secure, standards-based access to personal health information.

Overview​

This API empowers patients to access their health data through authorized third-party applications, supporting the patient's right to access their electronic health information as mandated by the 21st Century Cures Act. Healthcare providers can use this API to enable patient portal integrations, mobile health applications, and other patient-facing tools.

Key Features​

  • Patient-Controlled Access - Patients authorize and control access to their own health data
  • SMART on FHIR Launch - Supports both standalone and EHR-integrated app launches
  • Real-Time Data - Access to current patient information from provider EHR systems
  • Comprehensive Health Records - Full access to clinical, administrative, and financial data
  • Regulatory Compliance - Meets 21st Century Cures Act and ONC certification requirements
  • Secure Authentication - OAuth 2.0 with PKCE for enhanced security

Supported Use Cases​

Patient Portal Integration​

Integrate patient portals with EHR systems to provide seamless access to health records, test results, and care summaries.

Mobile Health Applications​

Enable mobile apps to access patient data for medication tracking, appointment scheduling, and health monitoring.

Personal Health Records​

Allow patients to aggregate their health information from multiple providers into personal health record systems.

Care Coordination Tools​

Support applications that help patients share their health information with family members, caregivers, or other healthcare providers.

Authentication & Authorization​

OAuth 2.0 Authorization Code Flow​

This API uses the OAuth 2.0 Authorization Code Flow with PKCE (Proof Key for Code Exchange) to ensure secure patient authentication and authorization.

Key Components:

  • Patient Consent - Patients explicitly authorize access to their health data
  • Scope-Based Access - Fine-grained permissions control what data can be accessed
  • Token-Based Security - Short-lived access tokens with optional refresh tokens
  • PKCE Support - Enhanced security for public clients (mobile apps, SPAs)

SMART App Launch Patterns​

Standalone Launch:

  • Patient initiates app launch independently
  • App redirects to provider's authorization server
  • Patient authenticates and grants consent

EHR Launch:

  • Provider EHR launches the app within clinical workflow
  • Context (patient, encounter) passed to the app
  • Streamlined authorization process

Implementation Standards​

This API implements multiple healthcare interoperability standards:

StandardVersionPurpose
FHIRR4Healthcare data exchange format
US Core6.1.0Core FHIR profiles for US healthcare
SMART on FHIR2.0OAuth 2.0 profiles for healthcare apps
OAuth 2.0RFC 6749Authorization framework
OpenID Connect1.0Identity layer on OAuth 2.0

Environment Information​

Production Environment​

  • Base URL: https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
  • Authorization: https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/authorize
  • Token Endpoint: https://fhir.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/token

Preview Environment​

  • Base URL: https://fhirtest.netsmartcloud.com/provider/patient-access/v2/{tenant-id}
  • Authorization: https://fhirtest.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/authorize
  • Token Endpoint: https://fhirtest.netsmartcloud.com/auth/{tenant-id}/oauth2/v1/token

Getting Started​

Prerequisites​

  1. CareConnect Tenant Access - Contact Netsmart to obtain your tenant ID
  2. Application Registration - Register your application to receive client credentials
  3. FHIR Knowledge - Basic understanding of FHIR R4 resources and operations
  4. OAuth 2.0 Implementation - Ability to implement OAuth 2.0 authorization code flow

Quick Start Steps​

  1. Discover Capabilities - Retrieve the CapabilityStatement to understand supported resources
  2. Configure Authentication - Set up OAuth 2.0 authorization code flow with PKCE
  3. Request Patient Authorization - Redirect patients to the authorization server
  4. Exchange Authorization Code - Trade authorization code for access token
  5. Access FHIR Resources - Make authenticated requests to retrieve patient data

Example: Get CapabilityStatement​

GET https://fhir.netsmartcloud.com/provider/patient-access/v2/{tenant-id}/metadata
Accept: application/fhir+json

Supported FHIR Resources​

This API provides access to the same comprehensive set of FHIR resources as outlined in the Provider APIs overview, organized by category:

  • Base Resources - Patient demographics and provider information
  • Clinical Resources - Conditions, procedures, observations, and medications
  • Workflow Resources - Encounters, care plans, and service requests
  • Financial Resources - Insurance coverage information
  • Specialized Resources - Documents, devices, and audit trails

For detailed information about each resource, including supported operations and search parameters, start with the CapabilityStatement to discover what's actually supported by this API.

Security & Privacy​

Patient Privacy Protection​

  • Minimum Necessary - Access limited to data necessary for the application's purpose
  • Patient Consent - Explicit patient authorization required for all data access
  • Audit Logging - All access attempts are logged for security monitoring
  • Data Encryption - All data transmitted over HTTPS/TLS

HIPAA Compliance​

  • Business Associate Agreements - Required for covered entities
  • Administrative Safeguards - Access controls and user authentication
  • Physical Safeguards - Secure data centers and infrastructure
  • Technical Safeguards - Encryption, audit logs, and access controls

Error Handling​

The API follows FHIR and OAuth 2.0 standards for error responses. Common error scenarios include:

  • Authentication Errors - Invalid or expired tokens
  • Authorization Errors - Insufficient permissions or scope
  • Resource Errors - Invalid resource requests or parameters
  • System Errors - Temporary service unavailability

For detailed error codes and troubleshooting guidance, see the Error Handling documentation.

Support Resources​

Next Steps​

Ready to start building? Here's what to do next:

  1. Review CapabilityStatement - Discover supported resources and operations
  2. Set Up Authentication - Implement OAuth 2.0 flows
  3. Try the Tutorial - Follow our Postman guide
  4. Test Integration - Use the preview environment to validate your implementation

This API enables powerful patient-centered applications while maintaining the highest standards of security and privacy. Contact Netsmart support for assistance with your integration.