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
Delivery Acknowledgement
High-level Delivery Acknowledgement Overview
esMD Delivery Acknowledgement is a vital part of the Electronic Submission of Medical Documentation (esMD) process. It enables healthcare providers to acknowledge the receipt of Electronic Medical Documentation Requests (eMDRs) or Letters. The delivery confirmation acknowledgement enables HIHs to indicate that providers have successfully received and can access clinical documents they receive through esMD. It also enables HIHs to indicate those times that providers encounter errors which prevent them from accessing the clinical documents they receive through esMD.
The following custom esMD FHIR profile resources and esMD FHIR REST APIs are used in the Delivery Acknowledgement 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.
- List Delivery Confirmation API – The List API is an esMD FHIR REST API that uses the Esmd-ListDeliveryConfirmation profile to submit delivery success acknowledgements or delivery failure acknowledgements for each clinical document that providers receive through esMD.
The esMD Delivery Acknowledgement process follows the steps that are summarized below:
- HIHs securely authenticate to the esMD System using the esMD Auth API.
- HIHs use the List Delivery Confirmation API to send a Delivery Acknowledgement to the esMD FHIR server using the Esmd-ListDeliveryConfirmation resource to inform the originating Review Contractor (RC) of each delivery success acknowledgement or delivery failure acknowledgement for each clinical document received from that RC.
esMD Delivery Acknowledgement Types
esMD Delivery Acknowledgements fall into one of the two types that are summarized below:
| Notification Category | Description |
| Provider Delivery Success Acknowledgement | The HIH indicates the provider acknowledged successful receipt of the clinical document with no errors. |
| Provider Delivery Failure Acknowledgement | The HIH indicates the provider acknowledged receipt of the clinical document but the provider is not able to use it due to an error condition. |
NOTE: Each of the Delivery Acknowledgement types listed above applies to the following supported esMD Lines of Business.
Supported esMD Lines of Business
The esMD FHIR Delivery Acknowledgement process enables HIHs to transmit Delivery Acknowledgements for clinical documents which are 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 |
Detailed Workflow for Transmitting Delivery Acknowledgements
The following diagram provides a description of the process that HIHs use for transmitting Delivery Acknowledgements to the esMD System.
Authentication/Token Generation:
- The HIH uses its clientId, client_secret, and Scope Header to authenticate using esMD's Authentication API.
- 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 POST requests.
- The clientId from the Auth token will be used to validate the identity of the HIH in subsequent steps of the notification retrieval process.
- 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.
- If authentication fails, an error is returned. Please refer to the Authentication API page for detailed information about the API.
Submit Delivery Acknowledgement
- In this step, the HIH uses the List Delivery Confirmation API, the POST method, and the Esmd-ListDeliveryConfirmation resource to send a Delivery Acknowledgement to the esMD FHIR server.
- esMD uses the clientId from the Auth token to validate the identity of the HIH such that esMD will only accept Delivery Acknowledgements for clinical documents that an HIH is authorized to access.
- The POST request includes the Auth token (Authorization header), Accept, and Content-Type Headers.
- HIHs use the ‘contained’ element within the Esmd-ListDeliveryConfirmation resource to send an OperationOutcome resource which contains either a Provider Delivery Success Acknowledgement or a Provider Delivery Failure Acknowledgement.
The following OperationOutcome resource fields are used to send Delivery Acknowledgements:
| OperationOutcome Element | Usage (Required/Optional) | Success Acknowledgement Element Value |
Failure Acknowledgement Element Value |
Success Acknowledgement with Metadata Error Element Value |
| severity | Required | information | error | information |
| code | Required | informational | exception | informational |
| diagnostics | Optional | Any success message as free-flow text | Any error message as free-flow text | Any free-flow text message which indicates success but with metadata errors. |
Successful Provider Delivery Acknowledgment Request
The following JSON is an example of a Successful Delivery Acknowledgement request that is sent from the HIH to esMD.
{
"resourceType": "List",
"id": "list782",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-ListDeliveryConfirmation"
],
"security": [
{
"system" : "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code" : "V",
"display" : "very restricted"
}
]
},
"contained": [
{
"resourceType": "OperationOutcome",
"id": "WBS0007236864EC-OperationOutcome",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-OperationOutcome"
]
},
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "Successful Provider delivery ack"
}
]
}
],
"extension": [
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
"valueString": "WBS0007236864EC"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-OrganizationId",
"valueString": "urn:oid:123.456.657.127"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-DeliveryDateTime",
"valueDateTime": "2025-03-21T11:25:40.111-04:00"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
"valueString": "1568425007"
}
],
"status": "current",
"mode": "working",
"title": "Submission Set Title",
"date": "2025-03-21T11:25:40-04:00",
"entry": [
{
"item": {
"reference": "#WBS0007236864EC-OperationOutcome"
}
}
]
}
Failed Provider Delivery Acknowledgment Request
The following JSON is an example of a Failed Delivery Acknowledgement request that is sent from the HIH to esMD.
{
"resourceType": "List",
"id": "list782",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-ListDeliveryConfirmation"
],
"security": [
{
"system" : "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code" : "V",
"display" : "very restricted"
}
]
},
"contained": [
{
"resourceType": "OperationOutcome",
"id": "RIA0007236843EC-OperationOutcome",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-OperationOutcome"
]
},
"issue": [
{
"severity": "error",
"code": "exception",
"diagnostics": "Error encountered during decoding the payload."
}
]
}
],
"extension": [
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
"valueString": "RIA0007236843EC"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-OrganizationId",
"valueString": "urn:oid:123.456.657.127"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-DeliveryDateTime",
"valueDateTime": "2025-03-21T11:25:40.111-04:00"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
"valueString": "1568425007"
}
],
"status": "current",
"mode": "working",
"title": "Submission Set Title",
"date": "2025-03-21T11:25:40-04:00",
"entry": [
{
"item": {
"reference": "#RIA0007236843EC-OperationOutcome"
}
}
]
}
Successful Provider Delivery ACK with Metadata Error Request
The following JSON is an example of a Successful Delivery Acknowledgement with Metadata Error request that is sent from the HIH to esMD.
{
"resourceType": "List",
"id": "list782",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-ListDeliveryConfirmation"
],
"security": [
{
"system" : "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code" : "V",
"display" : "very restricted"
}
]
},
"contained": [
{
"resourceType": "OperationOutcome",
"id": "VYP0007236790EC-OperationOutcome",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-OperationOutcome"
]
},
"issue": [
{
"severity": "information",
"code": "informational",
"diagnostics": "ok"
}
]
}
],
"extension": [
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
"valueString": "VYP0007236790EC"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-OrganizationId",
"valueString": "urn:oid:123.456.657.127"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-DeliveryDateTime",
"valueDateTime": "2025-03-18T11:25:40.111-04:00"
},
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
"valueString": "1568425007"
}
],
"status": "current",
"mode": "working",
"title": "Submission Set Title",
"date": "2025-03-21T11:25:40-04:00",
"entry": [
{
"item": {
"reference": "#VYP0007236790EC-OperationOutcome"
}
}
]
}
- esMD validates the Esmd-ListDeliveryConfirmation resource in the request and returns a success or failure response.
- Validation Success: esMD returns a success transaction response for a valid Esmd-ListDeliveryConfirmation request.
- Validation Failure: esMD returns an OperationOutcome with error message if invalid token or validation failures are encountered.
esMD Delivery Acknowledgement Validations
The esMD system applies Custom Validation, Profile-level Validation, and System Dependency Checks to the Esmd-ListDeliveryConfirmation resource to ensure conformity, accuracy, and consistency with esMD System processing.
NOTE: Refer to the List Delivery Confirmation API to view examples of the JSON which is sent from esMD.
Custom Validations
Custom validations are esMD-specific checks which are applied to individual fields to ensure they maintain data integrity and accuracy. The custom validations used by the esMD System for Delivery Acknowledgements are summarized in the table that follows.
| Validation Rule | Error Message | Comments |
| Valid Transaction ID from the downloaded eMDRs (Pre-Pay, Post-Pay, Post-Pay Others) and Letters. | Invalid esMD Transaction ID {0} received. | The Unique identifier that is assigned by the esMD System for the following LOBs eMDRs (Pre-Pay, Post-Pay, Post-Pay Others) and Letters received and processed to the HIH. The HIHs must ensure to include the same Transaction ID from the downloaded package while sending the Delivery Acknowledgement, confirming the receipt or failed to download the package. The same identifier is used by the esMD for tracking the transaction status. {0} = Transaction ID |
| Valid HIH OID associated with esMD. | Either HIH OID is invalid, or agreement has expired. Correct and resubmit. | The HIH OID registered with the esMD system must be active and must match the OID in the transaction used to send the Delivery Acknowledgement. |
| Combination of HIH OID and Transaction ID. | Invalid combination of OrganizationId {0} and TransactionId {1}. | The esMD assigned Unique Identifier and the associated HIH OID retrieved from the downloaded package must be the same in the Delivery Acknowledgement. {0} = Organization ID {1} = Transaction ID |
| Combination of HIH OID and Client ID. | Invalid combination of Organization ID and Client ID. | The associated HIH OID and the Client ID that is used to generate the Authentication Token must match. |
| Combination of Transaction ID and NPI. | Invalid Transaction ID {0} and NPI {1} combination. | The Transaction ID and the NPI must match from the downloaded package. {0} = Transaction ID {1} = NPI |
| Delivery Acknowledgement sent more than once. | Received Duplicate Provider Delivery Notification from HIH. | This validation fails if the HIH has sent the Delivery Acknowledgement more than once in case of success or failure. |
| Provider Delivery Date. | Either the Provider Delivery Date {0} is a future date or the delivery date is provided even before the letter is received by the HIH. | Timestamp for when clinical documents are delivered to providers. Ensures accurate tracking and accountability. Must be in FHIR-compliant format (yyyy-MM-ddTHH:mm:ss.SSS-TimeZone). This date cannot be a future date nor can it occur before the letter is received. {0} = Provider Delivery Date. |
Profile level Validations Profile-Level validations ensure that the Esmd-ListDeliveryConfirmation resource adheres to the Esmd-ListDeliveryConfirmation profile standards when single Delivery Acknowledgement transactions are submitted. The esMD system enforces these profile-level checks to verify that the resource structure and fields match the expected configuration defined by the profile. Profile-level validations are summarized in the table that follows.
| Metadata Element | FHIR Element Name | Description | Required/Optional | Length/Format |
| Transaction ID | Esmd-Ext-TransactionId | Unique identifier assigned by esMD System for tracking transactions. Used in esMD profiles for DocumentReference and ListDeliveryConfirmation. | Required | Alphanumeric |
| NPI | Esmd-Ext-NPI | A 10-digit unique identifier for healthcare providers used in administrative and financial transactions, compliant with HIPAA standards. | Required | 10-digit number |
| Organization ID | Esmd-Ext-OrganizationID | Sender HIH OID represents the sender’s registered OID when sending documents; must be numeric, 1-64 characters long. | Required | Numeric, 1-64 characters |
| Delivery Timestamp | Esmd-Ext-DeliveryDateTime | Timestamp for when clinical documents are delivered to providers. Ensures accurate tracking and accountability. Must be in FHIR-compliant format (yyyy-MM-ddTHH:mm:ss.SSS-TimeZone). | Required | yyyy-MM-ddTHH:mm:ss.SSS-TimeZone |
| Status | N/A | Indicates the current status of the delivery confirmation process. | Required | Alphanumeric |
| Mode | N/A | Indicates the working mode of the esMD system. | Required | Alphanumeric |
| Date | N/A | Represents the preparation date of the list. | Required | yyyy-MM-dd |
| OperationOutcome | Contained | The success or failure acknowledgment is sent to esMD using the Contained element with Operations Outcome inside the List resource. In case of success, the severity is information, code is informational, and diagnosis is optional which conveys the success. In case of failure, severity is error, code is exception. HIHs need to send the error details in diagnostics. | Required | JSON format |