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
The esMD Bundle API provides a streamlined method for Health Information Handlers (HIHs) to interact with the esMD system, supporting functionalities for both bundle submission and service registration.
/api/esmdf/ext/v1/fhirhttps://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhirhttps://cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir| Header | Description | Required | Data Type | Comments |
| Authorization | Authentication token from Auth API | Yes | String | Example: Bearer 3fis5elmln49c3fklkfs5v20ml |
| Content-Type | Content-Type must be application/fhir+json | yes | String | application/fhir+json |
| Accept | Accept must be application/fhir+json | yes | String | application/fhir+json |
Bundle Submission Request:
POST /api/esmdf/ext/v1/fhir HTTP/1.1
Host: dev.cpiapigateway.cms.gov
Authorization: Bearer {token}
Content-Type: application/fhir+json
Accept: application/fhir+json
{
"resourceType":"Bundle",
"id":"6ce2bb15-cc4e-4d2d-979c-fd4df85d26f8",
"meta":{
"profile":[
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-BundleSubmission"
],
"security":[
{
"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code":"V",
"display":"very restricted"
}
]
},
"type":"transaction",
"timestamp":"2025-04-05T11:25:40-04:00",
"entry":[
{
"fullUrl":"urn:uuid:49d2f890-828e-40ef-b05e-e755cbaf4ea2",
"resource":{
"resourceType":"List",
"id":"49d2f890-828e-40ef-b05e-e755cbaf4ea2",
"meta":{
"profile":[
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-ListSubmissionSet"
],
"security":[
{
"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code":"V",
"display":"very restricted"
}
]
},
"extension":[
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-LinesOfBusinessId",
"valueCode":"8.3"
},
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-OrganizationId",
"valueString":"urn:oid:123.456.657.130"
},
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-IntendedRecipient",
"valueCode":"urn:oid:2.16.840.1.113883.13.34.110.1.999.22"
},
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-UniqueId",
"valueString":"6ce2bb15-cc4e-4d2d-979c-fd4df85d26f8"
},
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
"valueString":"1234567893"
},
{
"url":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ResponseTypeCategory",
"valueString":"ResponseTypeCategory Value"
}
],
"status":"current",
"mode":"working",
"title":"Submission Set Title",
"date":"2025-04-05T11:25:40-04:00",
"entry":[
{
"item":{
"reference":"DocumentReference/0934339b-a755-47cb-a3c6-56849acb16b7"
}
}
]
},
"request":{
"method":"POST",
"url":"List"
}
},
{
"fullUrl":"0934339b-a755-47cb-a3c6-56849acb16b7",
"resource":{
"resourceType":"DocumentReference",
"id":"0934339b-a755-47cb-a3c6-56849acb16b7",
"meta":{
"profile":[
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-DocumentReference"
],
"security":[
{
"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code":"V",
"display":"very restricted"
}
]
},
"identifier":[
{
"system":"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Idn-UniqueId",
"value":"6ce2bb15-cc4e-4d2d-979c-fd4df85d26f8"
}
],
"status":"current",
"date":"2025-04-05T11:25:40-04:00",
"category":[
{
"coding":[
{
"system":"http://loinc.org",
"code":"47039-3",
"display":"Hospital Admission history and physical note"
}
]
}
],
"securityLabel":[
{
"coding":[
{
"system":"http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code":"V",
"display":"very restricted"
}
]
}
],
"content":[
{
"attachment":{
"id":"Document1",
"contentType":"application/pdf",
"url":"s3://uat-esmd-qurantine/6ce2bb15-cc4e-4d2d-979c-fd4df85d26f8/6ce2bb15-cc4e-4d2d-979c-fd4df85d26f8_1.xml",
"size":105255200,
"hash":"ec5c7d057aecbb918ba11c2554b9d230b147ad33d99f2161a58cfc19e27048eb",
"title":"pkpadmin",
"creation":"2025-04-05T11:25:40-04:00"
},
"format":{
"system":"urn:oid:1.3.6.1.4.1.19376.1.2.3",
"code":"urn:ihe:iti:xds-sd:pdf:2008"
}
}
],
"context":{
"facilityType":{
"coding":[
{
"system":"https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-FacilityTypeCodes",
"code":"hih"
}
]
}
}
},
"request":{
"method":"POST",
"url":"DocumentReference"
}
}
]
}
| 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. |
Success Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"resourceType": "Bundle",
"id": "d6e86a93-aa30-4e62-a7bb-a07af8a9e2e1",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-BundleSubmissionResponse"
],
"security": [
{
"system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
"code": "V",
"display": "very restricted"
}
]
},
"identifier": {
"system": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
"value": "IMQ0001235989EC"
},
"type": "transaction-response",
"link": [
{
"relation": "self",
"url": "http://terminology.esmduat.cms.gov:8099/fhir"
}
],
"entry": [
{
"response": {
"status": "201 Created",
"location": "List/192428/_history/1",
"etag": "1",
"lastModified": "2025-05-01T14:35:29.960-04:00",
"outcome": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
"code": "SUCCESSFUL_CREATE",
"display": "Create succeeded."
}
]
},
"diagnostics": "Successfully created resource \"List/192428/_history/1\". Took 74ms."
}
]
}
}
},
{
"response": {
"status": "201 Created",
"location": "DocumentReference/192429/_history/1",
"etag": "1",
"lastModified": "2025-05-01T14:35:29.960-04:00",
"outcome": {
"resourceType": "OperationOutcome",
"issue": [
{
"severity": "information",
"code": "informational",
"details": {
"coding": [
{
"system": "https://hapifhir.io/fhir/CodeSystem/hapi-fhir-storage-response-code",
"code": "SUCCESSFUL_CREATE",
"display": "Create succeeded."
}
]
},
"diagnostics": "Successfully created resource \"DocumentReference/192429/_history/1\". Took 44ms."
}
]
}
}
}
]
}
Sample Bundle Submission Failure Response - Unique ID Not Matching.
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"resourceType": "OperationOutcome",
"meta": {
"profile": [
"https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-BundleSubmissionResponse"
]
},
"extension": [
{
"url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
"valueString": "HJG0007228027EC"
}
],
"issue": [
{
"severity": "error",
"code": "processing",
"details": {
"coding": [
{
"system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
"code": "UNIQUE_ID_NOT_MATCHING",
"display": "Unique ID received in the bundle request do no match with the Unique ID sent in the PreSigned URL."
}
]
}
}
]
}