ESMD FHIR Implementation Guide
1.0.0 - esmd

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

Bundle Submission

Bundle Submission High-level Overview

The esMD FHIR Bundle Submission process uses custom esMD FHIR profile resources and esMD FHIR REST APIs to provide structured, secure interactions that enable HIH (Health Information Handlers) or Providers to authenticate, obtain presigned URLs, upload the document content for esMD supported Lines of Business (LOBs), and then submit the associated submission set metadata and document metadata. This process enables HIHs to securely authenticate and submit electronic clinical documents to esMD for forwarding to the designated Review Contractors (RCs).

The following custom esMD FHIR profile resources and esMD FHIR REST APIs are used in this process:

  1. Authentication API – The Authentication API (Auth API) is an esMD FHIR REST API that uses the Open Authorization (OAuth 2.0) framework to facilitate secure access to the esMD System by validating user credentials and providing access tokens for use in subsequent API requests.
  2. Generate Presigned URL API – The Generate Presigned URL API is an esMD FHIR REST API that makes use of the HL7 FHIR Parameters resource. The Parameters resource enables HIHs to request presigned URLs which are used to upload clinical documents. HIHs use this resource to submit the information for each document they wish to upload to esMD. The esMD System uses this information to generate a presigned URL for each document.
  3. Bundle Submission API – The Bundle Submission API is an esMD FHIR REST API that makes use of the custom esMD FHIR Esmd-BundleSubmission profile. This profile makes use of the following custom esMD FHIR resources:
    • Esmd-ListSubmissionSet – A custom esMD FHIR profile that extends the HL7 FHIR List resource. HIHs use this resource to send the submission set metadata related to the clinical document(s) which get uploaded to esMD with a presigned URL.
    • Esmd-DocumentReference – A custom esMD FHIR profile that extends the HL7 FHIR DocumentReference resource. HIHs use this resource to send document metadata, which includes the storage URL details, for each clinical XML document payload that was uploaded to esMD.

The esMD FHIR Bundle Submission process follows the steps that are summarized below:

  • HIHs securely authenticate to the esMD System using the Authentication API.
  • HIHs use the Generate Presigned URL API to request presigned URLs.
  • HIHs use the presigned URLs to upload each clinical XML document payload to esMD storage.
  • HIHs use the Bundle Submission API to send the submission set metadata and document metadata, which includes the storage URL details for each clinical XML document uploaded to esMD as part of the bundle.

Supported esMD Lines of Business

The esMD FHIR Bundle Submission process enables HIHs to submit clinical XML documents to the esMD System. The following esMD lines of business are supported:

Line of Business (LOB) CTC(s) LOB Description
ADR Responses 1 Response message sent for Additional Documentation Request (ADR)
Unsolicited PWK Documentation 7 Unsolicited Paperwork (PWK) Documentation
Ambulance 8.1 Prior Authorization (PA) Requests for Repetitive Scheduled Non-Emergent Ambulance Transport
HHPCR 8.3 Prior Authorization (PA) Requests for Home Health Pre-Claim Review request (HHPCR)
DMEPOS 8.4 Prior Authorization (PA) Requests for Durable Medical Equipment, Prosthetics/Orthotics & Services (DMEPOS)
HOPD 8.5 Prior Authorization (PA) Requests for Hospital Outpatient Department Services (HOPD)
IRF 8.6 Prior Authorization (PA) Requests for Inpatient Rehabilitation Facility (IRF)
First Level Appeal Requests 9 Requesting a First Level Appeal Request
Second Level Appeal Requests 9.1 Requesting a Second Level Appeal Request
ADMC Requests 10 Advanced Determination of Medicare Coverage Requests (ADMC)
RA Discussion Requests 11 Recovery Auditor Discussion (RAC) Requests
DME Discussion Requests 11.1 Durable Medical Equipment (DME) Phone Discussion Requests

Bundle Submission Elements by Lines of Business

The esMD FHIR Bundle Submission Elements page outlines the structured data elements required for submitting electronic documents and transactions using FHIR-based bundle submissions. It ensures standardized, efficient, and interoperable data exchange across all Lines of Business (LOBs) within the esMD ecosystem.

Refer esMD FHIR Bundle Submission Elements

Detailed Workflow for Submitting Clinical Documents using the esMD FHIR Bundle Submission Process

The following diagram and related steps provide a description of the process for submitting XML clinical document payloads for supported LOBs to esMD.

Cinque Terre

Generate the Authentication/Token

  1. The HIH uses its clientId, client_secret, and Scope Header to authenticate using the esMD Authentication API.
  2. If the authentication operation is successful, the HIH receives an authentication (Auth) token that is used for further communication with esMD.
    • This Auth token will be used in the Authorization header of subsequent POST transaction requests to obtain presigned URLs and upload clinical XML document payloads along with submission set metadata and document metadata.
  3. Authentication tokens are valid for 30 minutes, and automatically expire 30 minutes after they are issued. HIHs must request a new authentication token once the current token expires.
  4. If authentication fails, an error is returned.

Please refer to the Authentication API page for detailed information about the validations and error messages for this API.

Request Presigned URLs for File Upload

  1. The HIH uses the Generate Presigned URL API to send a request to esMD to generate presigned URLs. This request includes the HIH’s authentication token and the FHIR Parameters resource.
  2. The Parameters resource contains the HIH’s Organization ID (OID) and one or more fileinfo parameters such that each document to be uploaded has its own fileinfo parameters element. Each fileinfo element contains metadata that describes the document that is being uploaded to esMD.
  3. esMD performs several validation checks to ensure that the request meets specific requirements before generating the presigned URLs.
    • When a request contains multiple fileinfo elements, each one is independently validated.
    • A maximum combined file size of 200 MB can be uploaded using a single request.
  4. When the request is valid, a Parameters resource is returned which contains a presigned URL for each file in the request.
  5. When the request is invalid, esMD will reject the entire request and respond with an OperationOutcome that contains details of the error. The HIH must correct the error(s) and resubmit the request.

Review the Generate Presigned URL API documentation and the Parameters resource documentation to get more detail about the request and response validation, errors, and parameters.

NOTE: Presigned URLs are valid for 15 minutes after they are issued. If the HIH does not upload the clinical document using the presigned URL within the 15 minute window it will expire and the user will be required to request a new presigned URL.

Upload Clinical XML Documents using the Presigned URLs

  1. The HIH uses the POST method to submit an upload request for each clinical XML document payload to esMD storage.
  2. The upload request consists of the presigned URL, Header information (Auth token, Content-Type, Content-Length, Content-MD5 hash), and the Body (content of the clinical XML document).
    • HIHs must ensure that the MD5 hash of the file that is being uploaded matches the value of the MD5 hash that was provided in the presigned URL request.
  3. esMD returns a success status response when the file is successfully uploaded.
  4. esMD returns a failure status response when a file fails to upload to esMD.

NOTE: All files associated with the unique ID used to request the presigned URL must be uploaded before submitting the Esmd-BundleSubmission bundle.

Review the Generate Presigned URL API documentation and the Parameters resource documentation to get more details about the request and response parameters used to submit documents.

Use the Bundle Submission API to Submit the Submission Set Metadata and the Document Metadata for Clinical Documents that were Uploaded using Presigned URLs

  1. HIHs use the Bundle Submission API and the POST method to submit an Esmd-BundleSubmission resource.
  2. The submit transaction consists of the Auth token, Content-Type, Accept, and Esmd-BundleSubmission. The Esmd-BundleSubmission resource consists of the following components:
    • One Esmd-ListSubmissionSet resource - This resource contains the submission set metadata related to the clinical document(s). There must be only one esMD-ListSubmissionSet resource in the bundle.
    • One Esmd-DocumentReference resource - This resource contains the document metadata related to the clinical document including the storage URL. There must be only one Esmd-DocumentReference resource in the bundle. The Esmd-DocumentReference resource will contain attachment details for each document uploaded as part of the bundle.
  3. The Bundle Submission API enforces strict validation rules to ensure that document submissions conform to esMD standards for data integrity. Validations include schema validation checks and custom metadata validation checks. NOTE: HIHs must verify the following things to ensure an error-free bundle submission process:
    • Verify that a new unique ID is generated for every Esmd-BundleSubmission bundle.
    • Verify that the unique ID generated as part of the presigned URL matches the unique ID in the Esmd-ListSubmissionSet resource.
    • Verify that the total number of documents which are uploaded along with their respective filenames and information match the number of Esmd-DocumentReference resources along with filenames and information included in the Esmd-BundleSubmission bundle.
    • Verify that the unique ID and parent unique ID match if split submissions are uploaded.
    • Verify that the file names in the presigned URL match the filenames in the Esmd-BundleSubmission bundle and that no duplicate file names are used. Please refer to the following pages for complete information about the custom validations.
  4. esMD returns a success transaction response for valid Esmd-BundleSubmission requests.
  5. esMD returns an OperationOutcome response with errors when the Esmd-BundleSubmission request fails one or more validations.