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

Document Retrieval

High-level Document Retrieval Overview

The esMD FHIR Document Retrieval process uses custom esMD FHIR profile resources and esMD FHIR REST APIs to provide structured, secure interactions that enables HIH (Health Information Handlers) or Providers to authenticate, retrieve document references, then download or redownload the base64 binary encoded document content. This process enables HIHs to securely identify and download clinical documents and esMD system reference data files.

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

  • 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.
  • DocumentReference API – The DocumentReference API is an esMD FHIR REST API that makes use of the custom esMD FHIR Esmd-FindBundleDocumentReferences profile. This profile enables HIHs to use their access token to request a list of DocumentReference entries which include Binary URLs that provide access to download or redownload the base64 binary encoded document content of clinical documents and esMD system reference data files.
  • Binary API – The Binary API is an esMD FHIR REST API that makes use of the custom esMD FHIR esMD Binary profile which enables HIHs to use Binary URLs to directly download or redownload base64 binary encoded document content of clinical documents and esMD system reference data files.

The esMD FHIR Document Retrieval process follows the steps that are summarized below:

  1. Users securely authenticate to the esMD System using the esMD Auth API.
  2. Users use the esMD DocumentReference API to retrieve DocumentReference resource bundles which contain Binary URLs that enable the secure download of both structured or unstructured electronic clinical documents, and esMD system reference data files.
  3. Users use the esMD Binary API along with Binary URLs obtained in Step 2 to download or redownload the structured or unstructured clinical documents, and esMD system reference data files.

NOTE: Documents which are uploaded to the esMD System are subject to esMD's 90-day retention/purge policy. The purge policy requires all documents to be removed from the esMD System 90 days after their original upload date. The upload date is the date that the esMD Transaction Id is assigned. Documents which have been purged from the esMD System will not be available for downloading or redownloading.

Supported esMD Lines of Business

The esMD FHIR Document Retrieval process enables HIHs to download Electronic Medical Document Requests (eMDRs), Letters, Prior Authorization Rejections, and Prior Authorization Responses related to the following supported esMD lines of business:

Line of Business (LOB) CTC(s) LOB Description
eMDR Pre-Pay 2.5 Pre-Pay electronic medical document requests
eMDR Post-Pay 2.6 Post-Pay electronic medical document requests
eMDR Post-Pay-Other 2.6 Pre-Pay-Other electronic medical document requests
Letters 20 All types of Letters.
PA Reject 8.1, 8.3, 8.4,8.5, 8.6 A complete rejection made by the Review Contractor for any of the Prior Authorization requests received from the HIH for the following PA programs: Ambulance (8.1), HHPCR (8.3), DMEPOS (8.4), HOPD (8.5), IRF (8.6).
PA Response 8.1, 8.3, 8.4,8.5, 8.6 The PA decision response sent by the Review contractor for any of the Prior Authorization requests received from the HIH for the following PA programs: Ambulance (8.1), HHPCR (8.3), DMEPOS (8.4), HOPD (8.5), IRF (8.6).
esMD System Reference Data 18 esMD System Reference Data consists of various lists and categories of information that are critical for ensuring the efficient operation of esMD's document submission and retrieval workflows. This reference data is made available to HIHs using esMD's PULL approach methods. Refer to the esMD System Reference Data page for additional details.

Detailed Workflow for Downloading Documents and System Reference Data Files

The esMD FHIR Document Retrieval module processes query requests for the following actions related to download Electronic Medical Document Requests (eMDRs), Letters, Prior Authorization Rejections, Prior Authorization Responses and esMD System Reference Data files:

  • Download them based on their transaction status.
  • Redownload them based on their transaction status and transaction ID. This module supports pagination, query validation, and efficient data delivery to ensure providers (HIHs) can retrieve notification bundles and related electronic documents reliably and sequentially.

The following diagram and related steps provide a description of the process for downloading or redownloading Electronic Medical Document Requests (eMDRs), Letters, Prior Authorization Rejections, Prior Authorization Responses, and esMD System Reference Data files.

Cinque Terre

Detailed Document Retrieval Steps

Authentication/Token Generation:

  1. The HIH uses its clientId, client_secret, and Scope Header to authenticate using esMD's 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 for subsequent GET requests.
    • The clientId from the Auth token will be used to validate the identity of the HIH in subsequent steps of the retrieval process.
  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 API.

Get Document Reference Bundles:

  • In the second step, the HIH uses the Document Retrieval API to send a GET request to the esMD FHIR server to retrieve a list of DocumentReference resources which contain Binary URLs for Electronic Medical Document Requests (eMDRs), Letters, Prior Authorization Rejections, Prior Authorization Responses, and esMD System Reference Data files that are available for the requesting HIH to download or redownload.
  • The GET request includes the Auth token (Authorization header) and the following search parameters:
Search Parameter Required /Optional Description
transaction-status-type Optional The status of the transaction:
  • ready-to-download: Never downloaded yet.
  • processed: Already downloaded at least once.
    		•
    transactionid Optional esMD Transaction ID associated with the document submission. (Required if transaction-status-type = "processed").
    • esMD uses the clientId from the Auth token to validate the identity of the HIH such that access to the documents are limited to the authorized HIH.

    The following scenarios provide examples of how to use the esMD FHIR Document Retrieval Module and Document Reference API to retrieve the binary URLs that enable downloading of the base64 encoded binary documents.

    Scenario Query Syntax Query Outcome (Success)
    Download all documents for an organization that have never been downloaded. /fhir/DocumentReference?transaction-status-type=ready-to-download Returns a bundle of DocumentReference resources. Binary URL details will be available under the attachment URL details for each DocumentReference in the bundle.
    NOTE: If the transaction-status-type search parameter is not used, the system defaults to retrieving documents which have a transaction-status-type of ready-to-download.
    Redownload a document using a specific transaction Id. /fhir/DocumentReference?transaction-status-type=processed&transactionid =1234 Returns a bundle of DocumentReference resources. Binary URL details will be available under the attachment URL details for each DocumentReference in the bundle.

    The following validations and errors apply to GET requests which use the DocumentReference API to retrieve DocumentReference resource bundles with binary URLs.

    Validation Rule Error Message Comments
    The transactionid parameter is required when the trans-status-type is "processed". esMD requires Transaction ID when trans-status-type is processed. Correct and resubmit. The transactionid parameter is used in other validations that limit access to authorized users and enable compliance with esMD's purge policy.
    A valid combination of the requesting HIH’s organizationid and transactionid is required to redownload a document. The received TransactionId {1} is not associated with the requesting OrganizationId {0}. Correct TransactionId {1} and resubmit. This validation ensures that the requesting HIH is authorized to download or redownload the document.
    {0}is a dynamic placeholder for Organization Id and {1} is a dynamic placeholder for Transaction Id.
    The Organization Id is taken from the clientId in the Auth token.
    An active organization ID must be in the esMD database Either HIH OID is invalid or agreement has expired. Correct and resubmit. This validation is used to limit access to authorized users.
    • When the request passes all validations, esMD responds with a bundle that contains a maximum of 20 DocumentReference resources per bundle segment.
      • The esMD System uses a pagination feature which returns a multiple segment search set bundle that contains a maximum of 20 DocumentReference resources per segment. If search results contain more than 20 DocumentReference Resources, then the pagination feature provides the next bundle segment of 20 DocumentReference resources which have a "ready-to-download" status.
      • This process repeats until all DocumentReference resources are received by the HIH. When an HIH receives a bundle segment, the status of each DocumentReference resource within that segment is updated to "processed". Updating the status identifies the DocumentReference resource as being available to redownload. Please refer to the esMD Pagination Feature description for more details.
      • Each DocumentReference resource will contain a content element, and an attachment element to provide the path for the Binary URL of each specific document. Example: content -> attachment -> url.
    • When the request fails any of the validations, the esMD System returns an OperationOutcome response that contains a description of the errors.

    NOTE: After receiving the Binary URLs, HIHs may store the Binary URLs. Doing so enables the HIHs to redownload documents from esMD whenever they want to without having to generate a new request for the same documents. When using locally stored Binary URLs, HIHs must remember that document retrieval is subject to esMD's 90-day retention/purge policy. The purge policy requires all documents to be removed from the esMD System 90 days after their original upload date. The upload date is the date that the esMD Transaction Id is assigned. Documents which have been purged will not be available for downloading or redownloading.

    Retrieve the Documents using Binary URLs:

    1. In this final step, the HIH downloads the base64 binary encoded documents content using the respective binary URL which was obtained during Step 2.
    2. esMD will open an endpoint using the binary URL format: /Binary/{id}.
    3. For retrieval of documents or reference data files, {id} represents a unique filename.
    4. If errors occur with the request, esMD returns an OperationOutcome response that contains a description of the errors.

    NOTE: Documents which are uploaded to the esMD System are subject to esMD's 90-day retention/purge policy. The purge policy requires all documents to be removed from the esMD System 90 days after their original upload date. The upload date is the date that the esMD Transaction Id is assigned. Documents which have been purged from the esMD System will not be available for downloading or redownloading.

    The following validations and error messages apply to download operations for retrieving the base64 encoded binary documents using esMD's Binary API and Binary URLs:

    Validation Rule Error Message Comments
    An active organization ID must be in the esMD database Request contained an invalid organization ID. This validation is used to limit access to authorized users.
    A valid filename must be submitted in the binary URL Invalid filename {0} submitted in the binary request. This validation is used to ensure the file is present in esMD storage.
    {0}is a dynamic placeholder for filename.
    The filename must be associated with the requesting HIH. The requested filename {0} does not belong to the requesting HIH {1}. {1}is a dynamic placeholder for Organization Id and {0} is a dynamic placeholder for filename.
    The Organization Id is taken from the clientId in the Auth token.
    The system verifies both the transaction id timestamp and request date timestamp before providing access to the documents for download. If the difference between the dates exceeds 90 days, the user will not be able to download the documents because of the purge policy. The requested document {0} has been removed from the system and is no longer available for download due to the 90-day retention/purge policy. This validation is used to ensure compliance with esMD's purge policy. {0}is a dynamic placeholder for filename.