ESMD FHIR Implementation Guide - Local Development build (v1.0.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
Home
Official URL: https://terminology.esmduat.cms.gov:8099/fhir/ImplementationGuide/ESMD-FHIR-ImplementationGuide
This implementation guide (IG) has been created to describe the Electronic Submission of Medical Documentation (esMD) System's custom implementation of the Health Level 7 (HL7) Fast Healthcare Interoperability Resources(FHIR) healthcare data standard. It is designed for Health Information Handlers (HIHs)/Providers, Review Contractors (RCs), and other stakeholders who need to interact with the esMD System using FHIR standards.
The esMD FHIR IG describes the usage of esMD's REST APIs and defines esMD's custom profiles, extensions, value sets, and transaction flows that support seamless integration between HIHs/Providers, and esMD services for submission and retrieval of medical documentation. The initial esMD FHIR functionality supports transactions between HIHs/Providers and esMD.
Production Terminology Server URL
By default, all example references in the esMD FHIR Implementation Guide point to the UAT (User Acceptance Testing) environment. For production use, please refer to the following terminology server base URL:
Base URL: https://terminology.esmd.cms.gov:8099/fhir
Purpose
The purpose of the esMD FHIR IG is to ensure the proper implementation of esMD's custom FHIR resources and esMD FHIR APIs, along with the standard HL7 FHIR resources used within the esMD System to enable the exchange of clinical and administrative documents. This IG includes information that is necessary to enable the submission of base64 encoded documents, document metadata, and submission metadata, manage document workflow and notifications related to document processing, and ensure the interoperability of user client software with esMD's FHIR-compliant framework.
This guide outlines:
esMD's custom FHIR profiles that support document submission, document retrieval, error handing and notifications, provider service registration, provider delivery acknowledgments, and esMD system reference data retrieval.
Security considerations for using esMD's FHIR APIs.
The esMD FHIR IG covers the following key use cases:
Secure Authentication: Implementing the esMD Authentication API to facilitate secure access to the esMD system by validating user credentials and providing access tokens for subsequent API requests.
Secure File Uploads: Using the esMD Generate Presigned URL API and the HL7 FHIR Parameters profile to enable HIHs to securely upload clinical documents to esMD cloud storage without requiring direct access to the storage system.
Transmit Submission Bundles: Using the esMD Bundle Submission API and the custom esMD FHIR Esmd-BundleSubmission profile to send submission bundles to the esMD system. These bundles contain submission set metadata and document metadata, which includes the storage URL details, for each clinical XML document payload that is sent to esMD.
Submit Provider Registrations: Using the esMD Practitioner API and the custom esMD FHIR Esmd-Practitioner profile to transmit provider registration information to esMD by submitting a single registration information transaction for each provider. Also addressed is using the Bundle Practitioner API and the custom esMD FHIR Esmd-BundleServiceRegistration profile to submit information for multiple providers using a single batch bundle request.
Retrieving Documents: Using the Document Retrieval API and the custom esMD FHIR Esmd-FindBundleDocumentReferences profile to enable HIHs to download or redownload a list of clinical documents and esMD System Refence Data entries which include Binary URLs that enable HIHs to locate those files in esMD Storage. It also addresses using the Binary API and the custom esMD FHIR Esmd-Binary profile to directly download or redownload the base64 binary encoded content of clinical documents and esMD System Reference Data using the Binary URLs.
Submit Provider Delivery Acknowledgements: Using the Delivery Confirmation API and the custom Esmd-ListDeliveryConfirmation profile to submit delivery success acknowledgements or delivery failure acknowledgements for each clinical document received from a given RC.
NOTE: The scope of esMD's initial FHIR release is limited to Health Information Handlers (HIHs) who are responsible for handling clinical document submission on behalf of healthcare providers. Future releases will add features for Review Contractors (RCs) that review submitted clinical documentation for compliance with payer and/or regulatory requirements.
The HL7 FHIR standard defines a set of base profiles which are resources, frameworks and APIs that provide a common reference point for exchanging clinical documents, data, and metadata. This implementation guide defines the custom profiles which extend those base resources in a manner that conform to the unique requirements that govern how esMD must operate. These customizations generally specify:
Rules about which resource elements must be used (mandatory), may be used (optional/conditional), or are not used.
Rules about custom elements which have been added to support esMD operations, but are not part of the base specification.
Rules about which API features/parameters are used, and how.
Rules about which terminologies are used in particular elements.
Descriptions of how the resource elements and API features map to local requirements and/or implementations.
Click the Profiles Tab at the top of this page to view the categorized list of esMD custom FHIR profiles which are part of this release.
This implementation guide defines several custom esMD CodeSystems and ValueSets which are provided to ensure the consistency and interoperability of data exchanged through the esMD System.
CodeSystem: A FHIR CodeSystem functions as a master catalog of a specific category of codes. esMD's CodeSystems contain codes that address the following aspects of esMD's workflows:
Document Submission Status
Administrative Error Codes
Document Rejection Reasons
Review Contractor Status
esMD Document Types
Click the Terminology Tab above and select CodeSystem to view the list of esMD CodeSystems with links to information on how they are used.
ValueSet: A FHIR ValueSet consists of a set of codes from one or more CodeSystems which specify which codes can be used in a particular context. esMD's ValueSets contain codes that the following aspects of esMD processing.
Document Submission Status
Error and Rejection Codes
Document Types
Click the Terminology Tab above and select ValueSet to view the list of esMD ValueSets with links to information on how they are used.
The esMD System implements security using industry-standard mechanisms to ensure secure interactions between external systems and esMD FHIR REST APIs.
Click the Operational Procedures Tab and select Security for a description of esMD's security features and best practices for how using those features to ensure the integrity of transactions submitted to or received from esMD.
esMD's Security mechanisms include:
Open Authorization (OAuth) 2.0: Provides authorization and secure token-based access to esMD.
Mutual Transport Layer Security (mTLS): Ensures secure communication between esMD and external systems.
Role-based Access Control (RBAC): Ensures only authorized entities can submit or retrieve documentation using esMD.
This implementation guide provides details about esMD's FHIR workflows including RESTful FHIR operations, custom esMD FHIR profiles, and transaction flowcharts for the following workflows:
Bundle Submission: Provides the step-by-step process for uploading clinical documents to esMD using a presigned URL and transmitting document and submission metadata for the uploaded document.
Service Registration: Provides the step-by-step process for submitting provider service registration requests to esMD.
Notifications Retrieval: Provides the step-by-step process for retrieving Transaction Bundle Validation Success Response Notifications, Transaction Bundle Validation Failure Response Notification, Package Pickup Success or Failure Notification, and Administrative Error Notifications.
Document Retrieval: Provides the step-by-step process for retrieving clinical documents along with related metadata, and for retrieving esMD system reference data files from esMD.
Delivery Acknowlegement: Provides the step-by-step process for submitting provider delivery acknowledgements to esMD.
Currently supported workflows can be access using the esMD FHIR Workflows Tab located at the top of this page.
Detailed specifications for each of esMD's REST APIs can be accessed from the Rest APIs tab of the esMD FHIR Implementation Guide.
The esMD Implementation Guide is a living document. As such, it will be updated as esMD's FHIR APIs are optimized and additional features are added. Please check back regular