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

List Delivery Confirmation API

Overview

The Provider Delivery Acknowledgment is submitted by Health Information Handlers (HIHs) to confirm the delivery status (success or failure) of eMDR documents (Pre-Pay, Post-Pay, Post-Pay Other) and Letters. This acknowledgment includes whether the Provider was able to successfully decode the received package from esMD.

API Information

  • Purpose: Submit provider delivery success or failure acknowledgment.
  • Method: POST
  • Authorization: Requires Bearer Token from Auth API.

Endpoints

Environment Endpoint
UAT https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List
PROD https://cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List

Request Headers

Header Description Required Data Type Comments
Authorization Bearer token from Auth API Yes String Format: Bearer {token}
Accept Must be application/fhir+json Yes String
Content-Type Must be application/fhir+json Yes String

Provider Delivery Confirmation Examples

Successful Provider Delivery Acknowledgment Request

{
    "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"
            }
        }
    ]
}

Delivery Confirmation API Response Codes

Type Code Status Resolution
Success 200 OK Request processed successfully. No action needed.
Success 201 Created Resource created successfully. No action needed.
Error 400 Bad Request Missing or invalid headers or parameters. Check request headers or parameters and resubmit.
Error 401 Unauthorized Invalid client ID or client secret. Correct the details and resubmit.
Error 403 Forbidden Insufficient permissions or server configuration issues. Contact esMD Support.
Error 404 Not Found Invalid URL. Correct the endpoint URL and resubmit.
Error 412 Precondition Failed Precondition failed. Check the conditions and resubmit.
Error 422 Unprocessable Entity Metadata failure. Update metadata and resubmit.
Error 500 Internal Server Error Unexpected server error. Contact esMD Support.
Error 502 Bad Gateway Contact esMD Support.
Error 503 Service Unavailable Contact esMD Support.

Successful Provider Delivery Acknowledgment Response

{
    "resourceType": "List",
    "id": "24753",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2025-03-21T12:04:07.449-04:00",
        "source": "#NizRfvfyZLFphTyD",
        "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

{
    "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"
            }
        }
    ]
}

Failed Provider Delivery Acknowledgment Response

{
    "resourceType": "List",
    "id": "24754",
    "meta": {
        "versionId": "1",
        "lastUpdated": "2025-03-21T12:08:06.221-04:00",
        "source": "#pJWR4Zcwu6srV265",
        "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 Acknowledgement with Metadata Error Request

{
    "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"
            }
        }
    ]
}

Successful Provider Delivery Acknowledgement with Metadata Error Response

{
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
                        "code": "INVALID_TRANSACTION_ID_NPI_COMBINATION",
                        "display": "Transaction ID VYP0007236790EC and NPI 1568425007 combination is invalid."
                    }
                ]
            }
        },
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
                        "code": "INVALID_PROVIDER_DELIVERY_CONFIRMATION_DATE",
                        "display": "Either the Provider Delivery Date 2025-03-18 is a future date or the delivery date is provided even before the letter is received by the HIH."
                    }
                ]
            }
        }
    ]
}