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

Notifications Retrieval API

Overview

The esMD Notifications Retrieval API allows Health Information Handlers (HIHs) to retrieve various types of notifications related to esMD transactions. These notifications include:

  • Validation Successful
  • Validation Failures
  • Pickup Notifications
  • Administrative Error Notifications

API Information

  • Operation Name: /api/esmdf/ext/v1/fhir
  • Method: GET
  • Authorization: Requires a Bearer Token obtained via the Auth API.

Endpoints:

  • 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 Authentication token from Auth API Yes String Example: Bearer {token}
Accept Accept must be application/fhir+json No String application/fhir+json

Request Parameters

Parameter Name Required/Optional Description
transaction-status-type Optional The status of the transaction:
  • ready-to-download: Never downloaded yet.
  • processed: Already downloaded at least once.
    		•
    requesttype Optional The type of notification requested:
  • ADMIN_ERROR – Administrative Error Response.
  • VALIDATION_FAILURE – Validation failure response.
  • VALIDATION_SUCCESS – Validation success response.
  • PICKUP – Pickup success or failure notification response.
    		•
    uniqueid Optional The unique identifier assigned by the HIH to each document within the Submission Set. Required only when transaction-status-type = processed.

    Note: By default, if no search parameters are provided, the API will return all notifications that are ready for download.

    Response

    The API returns a FHIR Bundle conforming to the Esmd-FindBundleListNotifications profile. The response includes:

    • Status of the notification
    • Relevant error messages (if any)
    • Metadata including the unique ID used to track the notification

    Example API Usage

    Request:

    GET https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/List?transaction-status-type=ready-to-download
Authorization: Bearer [token]

    Response:

    {
    "resourceType": "Bundle",
    "id": "fa74b960-a1fe-4271-91c7-bd24d5e54972",
    "meta": {
        "profile": [
            "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-FindBundleListNotifications"
        ],
        "security": [
            {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                        "code": "V",
                        "display": "very restricted"
                    }
                ]
            }
        ]
    },
    "type": "searchset",
    "link": [
        {
            "relation": "self",
            "url": "https://dev.cpiapigateway.cms.gov/api/esmdf/v1/fhir/List?transaction-status-type=processed&uniqueid=AWSAUTO8T-60e40016-97ab-48ec-bbc4-4d5cd9120dea"
        }
    ],
    "entry": [
        {
            "fullUrl": "https://terminology.esmduat.cms.gov:8099/fhir/List/ZKG0007233150EC-ADMIN-ERROR",
            "resource": {
                "resourceType": "List",
                "id": "ZKG0007233150EC-ADMIN-ERROR",
                "meta": {
                    "profile": [
                        "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-FindListTransactionNotification"
                    ],
                    "security": [
                        {
                            "coding": [
                                {
                                    "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                                    "code": "V",
                                    "display": "very restricted"
                                }
                            ]
                        }
                    ]
                },
                "contained": [
                    {
                        "resourceType": "OperationOutcome",
                        "id": "ZKG0007233150EC-ADMIN-ERROR",
                        "issue": [
                            {
                                "severity": "error",
                                "code": "processing",
                                "details": {
                                    "coding": [
                                        {
                                            "system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-AdminErrors",
                                            "code": "ESMD_410",
                                            "display": "Cannot Read Files/Corrupt Files"
                                        }
                                    ]
                                },
                                "diagnostics": "RC sent administrative error response"
                            }
                        ]
                    }
                ],
                "status": "current",
                "mode": "working",
                "title": "response-notification-admin-error",
                "date": "2025-03-06T14:24:01.954-05:00",
                "extension": [
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
                        "valueString": "ZKG0007233150EC"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-UniqueId",
                        "valueString": "AWSAUTO8T-60e40016-97ab-48ec-bbc4-4d5cd9120dea"
                    },
                    {
                        "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-ReviewContractorOid",
                        "valueCode": "urn:oid:2.16.840.1.113883.13.34.110.1.999.1"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-LinesOfBusinessId",
                        "valueCode": "10"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-RequestId",
                        "valueString": "esMD-Administrative Response"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-StatusCode",
                        "valueCode": "ready-to-download"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-RCCreationDateTime",
                        "valueDateTime": "2025-03-06T14:24:01.955-05:00"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-RCSubmissionDateTime",
                        "valueDateTime": "2025-03-06T14:24:01.955-05:00"
                    }
                ],
                "entry": [
                    {
                        "item": {
                            "reference": "#ZKG0007233150EC-ADMIN-ERROR"
                        }
                    }
                ]
            }
        }
    ]
}

    Error Handling

    • Invalid Bearer Token: Returns 401 Unauthorized.
    • Invalid uniqueid when transaction-status-type = processed: Returns 422 Unprocessable Entity.
    • Server Issues: Returns 500 Internal Server Error.

    Error Codes & Troubleshooting

    Type Code Status Resolution
    Success 200 OK Request processed successfully. No action needed.
    Error 400 Bad Request Missing or invalid headers or parameters. Check 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 config issues. Contact esMD Support.
    Error 404 Not Found Invalid URL. Correct the endpoint URL 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.