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 API

Overview

The esMD Document Retrieval API enables Health Information Handlers (HIHs) to retrieve electronically delivered documents stored in secure esMD storage (mailbox). These documents include:

  • eMDR (Electronic Medical Documentation Requests)
  • LETTERS (Medical Review Letters)
  • PA RESPONSE (Prior Authorization Responses)
  • PA REJECT (Prior Authorization Rejections)
  • SystemReferenceInformation (System information critical to esMD's workflows)

API Information

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

Endpoints:

  • UAT: https://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/DocumentReference
  • PROD: https://cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/DocumentReference

Request Headers

Header Description Required Data Type Example
Authorization Authentication token from Auth API Yes String Bearer {token}
Accept Accept must be application/fhir+json No String application/fhir+json

Request Parameters

Search Parameter Required / Optional Description
transaction-status-type Optional The status of the transaction:
  • ready-to-download: Not yet downloaded.
  • processed: Already downloaded at least once.
    		•
    transactionid Optional esMD Transaction ID associated with the document submission. (Required if transaction-status-type = "processed").

    Sample Request

    GET /DocumentReference?transaction-status-type=ready-to-download
Authorization: Bearer [YourAccessToken]

    Response Details

    Sample Success Response (FHIR Bundle)

    {
   "resourceType":"Bundle",
   "id":"3f187b67-468e-4227-b2d8-1177dec8df78",
   "meta":{
      "profile":[
         "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-FindBundleDocumentReferences"
      ],
      "security":[
         {
                  "system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                  "code":"V",
                  "display":"very restricted"
               }
            
      ]
   },
   "type":"searchset",
   "total":1,
   "link":[
      {
         "relation":"self",
         "url":"https://dev.cpiapigateway.cms.gov/api/esmdf/v1/fhir/DocumentReference?transaction-status-type=ready-to-download"
      }
   ],
   "entry":[
      {
         "fullUrl":"https://terminology.esmduat.cms.gov:8099/fhir/DocumentReference/TXE0007232564EC-LETTERS",
         "resource":{
            "resourceType":"DocumentReference",
            "id":"TXE0007232564EC-LETTERS",
            "meta":{
               "profile":[
                  "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-FindDocumentReference"
               ]
            },
            "extension":[
               {
                  "url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
                  "valueString":"TXE0007232564EC"
               },
               {
                  "url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-OrganizationId",
                  "valueString":"urn:oid:123.456.657.126"
               },
               {
                  "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-NPI",
                  "valueString":"1992853964"
               },
               {
                  "url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-RequestType",
                  "valueString":"LETTERS"
               },
               {
                  "url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-LinesOfBusinessId",
                  "valueCode":"20"
               },
               {
                  "url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-StatusCode",
                  "valueCode":"ready-to-download"
               }
            ],
            "identifier":[
               {
                  "system":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Idn-LetterId",
                  "value":"AWSAUTO2T_10542720250305"
               }
            ],
            "status":"current",
            "date":"2025-03-05T10:54:31.053-05:00",
            "securityLabel":[
               {
                  "coding":[
                     {
                        "system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                        "code":"V",
                        "display":"very restricted"
                     }
                  ]
               }
            ],
            "content":[
               {
                  "attachment":{
                     "id":"TXE0007232564EC_20250305105429_1",
                     "contentType":"application/pdf",
                     "language":"en-US",
                     "url":"/Binary/TXE0007232564EC_20250305105429_1",
                     "size":17033,
                     "hash":"df3c2fab54ff1ac8c0bd2bb602e7c39d916b0d916e3c06ebc0ae7f99058910b9",
                     "title":"LETTERS",
                     "creation":"2025-03-05T10:54:29.625-05:00"
                  },
                  "format":{
                     "system":"https://terminology.esmduat.cms.gov:8099/fhir/ValueSet/Esmd-VS-FormatCode",
                     "code":"urn:ihe:iti:xds-sd:pdf:2008",
                     "display":"Unstructured Clinical Document (PDF)"
                  }
               },
               {
                  "attachment":{
                     "id":"TXE0007232564EC_20250305105429_2",
                     "contentType":"application/json",
                     "language":"en-US",
                     "url":"/Binary/TXE0007232564EC_20250305105429_2",
                     "size":9198,
                     "hash":"81d68f49eae77c3473e217879c7c403e7c96829b4cc31f5b13a999fbc5b93802",
                     "title":"LETTERS",
                     "creation":"2025-03-05T10:54:29.695-05:00"
                  },
                  "format":{
                     "system":"https://terminology.esmduat.cms.gov:8099/fhir/ValueSet/Esmd-VS-FormatCode",
                     "code":"urn:ihe:iti:xds-sd:text:2008",
                     "display":"Unstructured Clinical Document (Text)"
                  }
               }
            ],
            "context":{
               "facilityType":{
                  "coding":[
                     {
                        "system":"https://terminology.esmduat.cms.gov:8099/fhir/ValueSet/Esmd-VS-FacilityTypeCode",
                        "code":"cms-rc",
                        "display":"CMS Review Contractor"
                     }
                  ]
               }
            }
         }
      }
   ]
}

    Sample Invalid Request

    GET /DocumentReference?transaction-status-type=processed
Authorization: Bearer [YourAccessToken]

    Sample Failure Response (Invalid Transaction ID)

    {
    "resourceType": "OperationOutcome",
    "meta": {
        "profile": [
            "http://internal-tf-val-esmd-apps-1968496636.us-east-1.elb.amazonaws.com:8099/fhir/StructureDefinition/Esmd-OperationOutcome"
        ]
    },
    "issue": [
        {
            "severity": "error",
            "code": "processing",
            "details": {
                "coding": [
                    {
                        "system": "http://internal-tf-val-esmd-apps-1968496636.us-east-1.elb.amazonaws.com:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
                        "code": "MISSING_REQUIRED_TRANSACTION_ID_PARAMETER",
                        "display": "esMD requires Transaction ID when trans-status-type is processed. Correct and resubmit."
                    }
                ]
            }
        }
    ]
}

    Security Considerations

    • Authentication: Only authorized users with valid Bearer Tokens can access the API.
    • Data Encryption: All data is transmitted over HTTPS with TLS 1.2+ encryption.
    • Access Control: Only users with correct client_id and client_secret can make requests.
    • Logging & Auditing: All transactions are logged for audit purposes.

    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.