Skip to main content

Payer Patient Access API

The Payer Patient Access API enables health plan members to securely access their own health and coverage information from payer systems. This FHIR R4-compliant API supports member-facing applications and follows SMART on FHIR specifications to ensure secure, standards-based access to personal health information, claims data, and benefits information.

Overview​

This API empowers health plan members to access their health data through authorized third-party applications, supporting member rights to access their electronic health information as mandated by the CMS Interoperability Rules and 21st Century Cures Act. Health plans can use this API to enable member portal integrations, mobile health applications, and other member-facing tools.

Key Features​

  • Member-Controlled Access - Members authorize and control access to their own health and coverage data
  • SMART on FHIR Launch - Supports both standalone and payer-integrated app launches
  • Comprehensive Health Records - Access to clinical data, claims, and benefits information
  • Claims and Benefits Data - Coverage details, explanation of benefits, and claims history
  • Regulatory Compliance - Meets CMS Interoperability Rules and ONC certification requirements
  • Secure Authentication - OAuth 2.0 with PKCE for enhanced security

Supported Use Cases​

Member Portal Integration​

Integrate member portals with payer systems to provide seamless access to health records, claims, benefits, and coverage information.

Mobile Health Applications​

Enable mobile apps to access member data for medication tracking, claims monitoring, and benefits utilization.

Personal Health Records​

Allow members to aggregate their health information from multiple payers and providers into personal health record systems.

Benefits and Claims Tracking​

Support applications that help members understand their coverage, track claims status, and manage healthcare expenses.

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 member authentication and authorization.

Key Components:

  • Member Consent - Members explicitly authorize access to their health and coverage 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:

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

Payer Launch:

  • Payer system launches the app within member workflow
  • Context (member, coverage) 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/payer/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/payer/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 Member Authorization - Redirect members to the authorization server
  4. Exchange Authorization Code - Trade authorization code for access token
  5. Access FHIR Resources - Make authenticated requests to retrieve member data

Example: Get CapabilityStatement​

GET https://fhir.netsmartcloud.com/payer/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 Payer APIs overview, organized by category:

  • Base Resources - Member demographics and provider information
  • Clinical Resources - Conditions, procedures, observations, and medications
  • Workflow Resources - Encounters, care plans, and service requests
  • Financial Resources - Coverage and explanation of benefits
  • 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.

Payer-Specific Features​

Coverage Information​

Access comprehensive insurance coverage details including:

  • Active and historical coverage periods
  • Benefit categories and limitations
  • Cost-sharing information
  • Network restrictions

Claims and Benefits Data​

Retrieve explanation of benefits and claims information:

  • Claims history and status
  • Benefit utilization
  • Cost-sharing details
  • Provider payment information

Member Context​

Member-specific data access ensures:

  • Only authorized member data is accessible
  • Proper consent and authorization workflows
  • Audit logging for member data access
  • Privacy protection and compliance

Security & Privacy​

Member Privacy Protection​

  • Minimum Necessary - Access limited to data necessary for the application's purpose
  • Member Consent - Explicit member 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 member-centered applications while maintaining the highest standards of security and privacy. Contact Netsmart support for assistance with your integration.