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

Binary API

Overview

The esMD Binary API enables HIHs to download or re-download base64-encoded clinical documents related to eMDRs, Letters, PA Rejections, PA Responses, and System Reference Information.

Download Payload

API Information

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

Endpoints

  • UAT: https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/Binary/{id}
  • PROD: https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/Binary/{id}

{id} - The filename of the document.

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

Sample Download Request

GET /Binary/TXE0007232564EC_20250305105429_2
Authorization: Bearer [YourAccessToken]

Response

Sample Success Response

{
    "resourceType": "Binary",
    "id": "3f187b67-468e-4227-b2d8-1177dec8df78",
    "meta": {
        "profile": [
            "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Binary"
        ],
        "security": [
            {
                "coding": [
                    {
                        "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                        "code": "V",
                        "display": "very restricted"
                    }
                ]
            }
        ]
    },
    "contentType": "application/json",
    "data": "PD94bWwgdmVyc2lvbj0nMS4wJyBlbmNvZGluZz0nVVRGLTgnPz4KPG5zMDpDbGluaWNhbERvY3VtZW50..."
}

Sample Failure 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_FILENAME",
                        "display": "Invalid filename TXE0007232564EC_20250305105429_23 submitted in the binary request."
                    }
                ]
            }
        }
    ]
}

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.