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

Bundle Practitioner API

Overview

The esMD FHIR Service Registration workflow enables Health Information Handlers (HIHs) to register medical practitioners (providers) in the esMD System, allowing them to send and receive Electronic Medical Documentation Request (eMDR) letters and other clinical documents electronically.

The Bundle Practitioner API supports the batch bundle registration method where multiple providers are registered using one request.

This document outlines API endpoints, request structure, response format, and error-handling mechanisms required for successful integration.

Note – NPI Registration in NPPES for the FHIR API: Existing NPPES registrations will remain unchanged. Organizations may continue using "CONNECT" as the endpoint type with the HIH endpoint/OID as the endpoint. However, for new NPI registrations submitted after the July 2025 Go-Live, HIHs onboarding to the esMD FHIR API can specify "FHIR API" as the endpoint type and set the endpoint to: https://cpiapigateway.cms.gov/api/esmdf/v1/fhir/Practitioner/{id}

API Information

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

Endpoints:

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

Request Headers

Header Description Required Data Type Comments
Authorization Authentication token from Auth API Yes String Example: Bearer {token}
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

Sample Bundle of Practitioners 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": "283084a6-ae8f-42c6-b495-43244b4c370d",
    "meta": {
        "profile": [
            "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-BundleServiceRegistration"
        ],
        "security": [
            {
                "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                "code": "V",
                "display": "very restricted"
            }
        ]
    },
    "type": "batch",
    "timestamp": "2025-04-13T12:00:00Z",
    "entry": [
        {
            "fullUrl": "urn:uuid:1",
            "resource": {
                "resourceType": "Practitioner",
                "id": "P1283084a6-ae8f-42c6-b495-43244b4c370d",
                "meta": {
                    "profile": [
                        "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Practitioner"
                    ],
                    "security": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                            "code": "V",
                            "display": "very restricted"
                        }
                    ]
                },
                "telecom": [
                    {
                        "system": "phone",
                        "value": "555-123-4567",
                        "use": "work"
                    }
                ],
                "name": [
                    {
                        "family": "Bone1",
                        "given": [
                            "Ronald1"
                        ],
                        "prefix": [
                            "Dr"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "work",
                        "line": [
                            "1003 HEALTHCARE DR"
                        ],
                        "city": "AMHERST",
                        "state": "MA",
                        "postalCode": "01002"
                    }
                ],
                "gender": "male",
                "active": true,
                "extension": [
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
                        "valueString": "1467487009"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ProviderTaxId",
                        "valueString": "HIH1234"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ActionRequestedCode",
                        "valueCode": "A"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceCode",
                        "valueCode": "EEP"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceStartDate",
                        "valueDate": "2025-05-01"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceEndDate",
                        "valueDate": "2025-12-31"
                    }
                ]
            },
            "request": {
                "method": "PUT",
                "url": "Practitioner/P1283084a6-ae8f-42c6-b495-43244b4c370d"
            }
        },
        {
            "fullUrl": "urn:uuid:1",
            "resource": {
                "resourceType": "Practitioner",
                "id": "P2283084a6-ae8f-42c6-b495-43244b4c370d",
                "meta": {
                    "profile": [
                        "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Practitioner"
                    ],
                    "security": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/v3-Confidentiality",
                            "code": "V",
                            "display": "very restricted"
                        }
                    ]
                },
                "telecom": [
                    {
                        "system": "phone",
                        "value": "555-123-4568",
                        "use": "work"
                    }
                ],
                "name": [
                    {
                        "family": "Bone2",
                        "given": [
                            "Ronald2"
                        ],
                        "prefix": [
                            "Dr"
                        ]
                    }
                ],
                "address": [
                    {
                        "use": "work",
                        "line": [
                            "1004 HEALTHCARE DR"
                        ],
                        "city": "AMHERST",
                        "state": "MA",
                        "postalCode": "01002"
                    }
                ],
                "gender": "male",
                "active": true,
                "extension": [
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
                        "valueString": "1457396376"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ProviderTaxId",
                        "valueString": "HIH1234"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ActionRequestedCode",
                        "valueCode": "A"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceCode",
                        "valueCode": "EEP"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceStartDate",
                        "valueDate": "2025-10-01"
                    },
                    {
                        "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ServiceEndDate",
                        "valueDate": "2025-12-31"
                    }
                ]
            },
            "request": {
                "method": "PUT",
                "url": "Practitioner/P2283084a6-ae8f-42c6-b495-43244b4c370d"
            }
        }
    ]
}

Bundle Practitioner 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.

Success Response

{
    "resourceType": "Bundle",
    "id": "1a7e613e-cf49-4d45-a772-e5fe75c94a5d",
    "meta": {
        "profile": [
            "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-BundleServiceRegistrationResponse"
        ],
        "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": "AWW0001235990EC"
    },
    "type": "batch-response",
    "link": [
        {
            "relation": "self",
            "url": "http://terminology.esmduat.cms.gov:8099/fhir"
        }
    ],
    "entry": [
        {
            "response": {
                "status": "201 Created",
                "location": "Practitioner/P1283084a6-ae8f-42c6-b495-43244b4c370d/_history/1",
                "etag": "1",
                "lastModified": "2025-05-01T14:39:10.808-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_UPDATE_AS_CREATE",
                                        "display": "Update as create succeeded."
                                    }
                                ]
                            },
                            "diagnostics": "Successfully created resource \"Practitioner/P1283084a6-ae8f-42c6-b495-43244b4c370d/_history/1\" using update as create (ie. create with client assigned ID). Took 590ms."
                        }
                    ]
                }
            }
        },
        {
            "response": {
                "status": "201 Created",
                "location": "Practitioner/P2283084a6-ae8f-42c6-b495-43244b4c370d/_history/1",
                "etag": "1",
                "lastModified": "2025-05-01T14:39:11.521-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_UPDATE_AS_CREATE",
                                        "display": "Update as create succeeded."
                                    }
                                ]
                            },
                            "diagnostics": "Successfully created resource \"Practitioner/P2283084a6-ae8f-42c6-b495-43244b4c370d/_history/1\" using update as create (ie. create with client assigned ID). Took 65ms."
                        }
                    ]
                }
            }
        }
    ]
}

Failure Responses

Example: Duplicate NPI-HIH Combination

{
    "resourceType": "Bundle",
    "id": "ca40eb3f-fc05-4c37-bd3d-7e3408857cec",
    "type": "batch-response",
    "link": [
        {
            "relation": "self",
            "url": "https://terminology.esmduat.cms.gov:8099/fhir"
        }
    ],
    "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": [
        {
            "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-TransactionId",
            "valueString": "PBC0007230909EC"
        }
    ],
    "entry": [
        {
            "response": {
                "status": "202 validation failure",
                "outcome": {
                    "resourceType": "OperationOutcome",
                    "issue": [
                        {
                            "severity": "error",
                            "code": "processing",
                            "details": {
                                "coding": [
                                    {
                                        "system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
                                        "code": "COMBINATION_NPI_HIH",
                                        "display": "The HIH OID urn:oid:123.456.657.126 and NPI 1205873338 received for Action Code A is already registered with the submitting HIH or other HIH."
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        },
        {
            "response": {
                "status": "202 validation failure",
                "outcome": {
                    "resourceType": "OperationOutcome",
                    "issue": [
                        {
                            "severity": "error",
                            "code": "processing",
                            "details": {
                                "coding": [
                                    {
                                        "system": "https://terminology.esmduat.cms.gov:8099/fhir/CodeSystem/Esmd-CS-ErrorOrWarningCodes",
                                        "code": "COMBINATION_HIH_NPI",
                                        "display": "The Action Code R Received in the Registration Request is not allowed for NPI 1609174218 as association with the HIH OID does not exist in esMD."
                                    }
                                ]
                            }
                        }
                    ]
                }
            }
        }
    ]
}