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

Es MD Service Registration

esMD Service Registration High-level Overview

The esMD FHIR Service Registration process uses custom esMD FHIR profile resources and esMD FHIR REST APIs that enable Health Information Handlers (HIHs) to register healthcare providers using their National Provider Identifiers (NPIs) to the esMD System. Registration enables those providers to send and receive Electronic Medical Documentation Request (eMDR) letters using the esMD System. The esMD System supports two registration methods:

  1. Registration of an individual provider using a practitioner resource.
  2. Bulk registration of multiple providers simultaneously using a batch bundle request transaction.

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://val.cpiapigateway.cms.gov/api/esmdf/ext/v1/fhir/Practitioner/{id}

The following custom esMD FHIR profile resources and esMD FHIR REST APIs are used by the Service Registration process:

  • Authentication API – The Authentication API (Auth API) is an esMD FHIR REST API that uses the Open Authorization (OAuth 2.0) framework to facilitate secure access to the esMD System by validating user credentials and providing access tokens for use in subsequent API requests.
  • Practitioner API – The Practitioner API is an esMD FHIR REST API that uses the custom esMD FHIR Esmd-Practitioner profile to transmit registration information for a single provider to esMD. This information includes provider’s personal details, and related action requests.
  • Bundle Practitioner API - The Esmd-PractitionerBundle API is an esMD FHIR REST API that uses the custom esMD FHIR Esmd-BundleServiceRegistration profile to transmit registration information for multiple providers to esMD using a batch bundle request. This information includes provider’s personal details, and related action requests.

Both the Practitioner API and PractitionerBundle API support the following Action Requests for Service Registration transactions:

Action Code Action Request Description
A Add a new provider or service
E Sending the ADRs only as eMDR
R Remove provider or service

The esMD Service Registration process follows the steps that are summarized below:

  1. HIHs securely authenticate to the esMD System using the esMD Authentication API.
  2. HIHs upload individual provider registration transactions, or multiple provider registrations using a batch bundle request.
  3. esMD validates each request and returns a structured response to the submitting HIH which indicates the registration request was successful, or it provides details of specific issues which caused the registration request to fail.

Supported esMD Lines of Business

The esMD FHIR Service Registration process enables HIHs to submit Service Registration requests to esMD and supports the following esMD line of business:

Line of Business (LOB) CTC LOB Description
Service Registration 5 Service Registration Request

Detailed Workflow for Individual Provider Service Registration Requests

The following diagram and related steps provide a description of the process for submitting individual provider registration requests to esMD.

Practitioner workflow

Generate the Authentication Token

  1. The HIH uses its clientId, client_secret, and Scope Header to authenticate using the esMD Authentication API.
  2. If the authentication operation is successful, the HIH receives an authentication (Auth) token that is used for further communication with esMD. o This Auth token will be used in the Authorization header of subsequent transactions to submit service registration requests.
  3. Authentication tokens are valid for 30 minutes, and automatically expire 30 minutes after they are issued. HIHs must request a new authentication token once the current token expires.
  4. If authentication fails, an error is returned. Please refer to the Authentication API page for detailed information about the validations and error messages for this API.

Submit Individual Practitioner Request

  1. The HIH uses the Practitioner API and the PUT method to submit a request that includes the Auth token (Authorization header), Practitioner ID, and the esMD FHIR Esmd-Practitioner resource which is populated with the practitioner’s information.
    • The same operation is used for all supported Action Requests (A, E, and R).
    • The Practitioner ID is a required parameter.
    • Example: PUT ( Token + /Practitioner/{id})

esMD Validates the Request and Returns a Structured Response

  1. esMD validates the request and returns a success or failure response as follows:
    • Validation Success: esMD returns a success response with the 201 Created status.
    • Invalid token or invalid header: esMD rejects the entire request and responds with an OperationOutcome that contains details of the error. The HIH must correct the error(s) and resubmit the request.

Detailed Workflow for Bulk Provider Service Registration Requests

The following diagram and related steps provide a description of the process for submitting bulk provider registration requests to esMD.

Bundle Practitioner workflow

Generate the Authentication Token

  1. The HIH generates an authentication token using the same Generate the Authentication Token procedure used to submit individual Service Registration Requests.

Submit Bulk Service Registration Request

  1. The HIH uses the PractitionerBundle API and the POST method to submit a batch bundle request that includes the Auth token (Authorization header) and information for multiple practitioners (Practitioner ID and esMD FHIR Esmd-Practitioner resource) Each practitioner must be submitted using the PUT method.
    • The same operation is used for all supported Action Requests (A, E, and R).
    • The Practitioner ID is a required parameter.
    • Example: Token + (POST / ) with multiple practitioners (PUT /Practitioner/{id} )[1..*])
  2. If an HIH needs to register more than 10 providers, the HIH must divide the registration requests into separate batches, each containing a maximum of 10 providers.
    • The batch bundle registration request will fail if more than 10 providers are submitted in a single batch using the batch bundle registration request.
    • HIHs shall receive an error response that informs the HIH of the need to adhere to the batch size limit.

esMD Validates the Request and Returns a Structured Response

  1. esMD validates the batch bundle request and returns a success and/or failure responses as follows:
    • Validation Success: esMD returns a batch bundle response that contains a 201 Created status for each successfully validated Esmd-Practitioner resource in the bundle.
    • Validation Failure: esMD returns a batch bundle response that contains a 202 Failure status for each Esmd-Practitioner resource in the bundle that failed validation.
    • Invalid token or Invalid headers: esMD returns a batch bundle response that contains an OperationOutcome with errors for the Bundle Practitioner API. The HIH must correct the error(s) and resubmit the request.

esMD Service Registration Validations

The esMD system applies Profile-level Validations, Custom Validations, and System Dependency Checks to the Esmd-Practitioner resource to ensure conformity, accuracy, and consistency with esMD System processing.

Profile level Validations

Profile-Level validations ensure that the Practitioner resource adheres to the Esmd-Practitioner profile standards when single provider transactions are submitted, or the Esmd-PractitionerBundle profile standard when batch bundle provider registration transactions are submitted. The esMD system enforces these profile-level checks to verify that the Practitioner resource structure and fields match the expected configuration defined by the respective profile.

Examples of profile-level validations include, but are not limited to the following:

  • Ensure that the resourceType is set to "Practitioner."
  • Ensures that the Meta.profile URL includes either the Esmd-Practitioner or Esmd-PractitionerBundle profile.
  • Ensures that fields like name.family, identifier.value, and address meet format requirements when they are present in the request.

System Dependency Checks

The esMD Service Registration workflow is subject to the following system dependency checks:

  • All National Provider Identifier (NPI) numbers are cross-referenced with the National Plan and Provider Enumeration System (NPPES) to ensure their validity and accuracy
  • The esMD system checks the HIH Organizational Identifier (OID) extracted from the client ID received in the Authentication Token to ensure it is registered and active in the esMD system.

Custom Validations

Custom validations are esMD-specific checks which are applied to individual fields to ensure they maintain data integrity and accuracy. The custom validations used by the esMD System are summarized in the table that follows.

Nr Metadata Element FHIR Element Name Description Required/Optional Length/ Format Validation Rule Error Message
1 Action Requested Esmd-Ext-ActionRequestedCode The "Action Requested" code is used to specify the desired action to be performed on a provider in the context of requesting to register for a service. Here are the possible actions:
1. A (Add a new provider): This action requests the addition of a new provider to the system. When this code is used, the esMD system will add the specified provider to the list of active participants.
2. E (Sending the ADRs only as eMDR): This action indicates that only the ADRs (Additional Documentation Requests) will be sent in the form of an eMDR (electronic Medical Documentation Request). The provider's data is not being changed, but the system will handle the ADRs as an eMDR.
3. R (Remove provider or service): This action requests the removal of a provider from a service. When this code is used, the Provider will be removed from the associated service. 		R The only value accepted for Action Codes A, E, R.
Note: NPI must already be in the esMD system for sending a request with an action code 'E'. 		For a request with Action Code ‘E’ the NPI/Provider must be active and present in the esMD database and NPPES. The Action Code 'E' Received in the Registration Request is not allowed for NPI {0} as association with the HIH OID does not exist in esMD. Correct and resubmit.
{0} = NPI
2 Start Date Esmd-Ext-ServiceStartDate The Start Date refers to the specific day when a Provider would like to register for a particular service. The Start Date is ‘Optional’ for any action codes (A, E or R). If provided, the date must be either a current or future date to be accepted by esMD. Past dates are not accepted. O Start Date format: YYYY-MM-DD
Where:
YYYY = Year
MM = Month
DD = Day 		If Start Date is sent, it must be in valid format, Ex: YYYY-MM-DD
Start Date must be either current or future date. 		Start Date should either be current or future date for action code: {0}
{0} = Action code
3 End Date Esmd-Ext-ServiceEndDate End date is optional; it cannot be lesser than the start date. O End Date format: YYYY-MM-DD
Where:
YYYY = Year
MM = Month
DD = Day 		If End Date is sent, it must be in valid format, Ex: YYYY-MM-DD
End Date must be greater than the Start Date. 		End Date cannot be lesser than start date.
4 NPI Esmd-Ext-ProviderNumber A National Provider Identifier (NPI) is a unique 10-digit number that identifies healthcare providers for use in administrative and financial transactions. The NPI is a Health Insurance Portability and Accountability Act (HIPAA) Administrative Simplification Standard. R 1. Length must be 10 numeric.
Example: 1234567890 		1. NPI must be unique and valid for any of the submitted Action Codes "A", "E", "R".
2. Maximum of 10 NPIs per Practitioner Bundle.
3. Valid NPI consent Check against NPPES system for Action Code "A" (Add) or "E" (Edit), the system will ensure the NPI is active in the NPPES system.
4. The system, when performing the NPPES consent check for the received NPI, will ensure it has the right value.
Ex: Correct value is 'CMS esMD eMDR' in the [useOtherDescription] field.
5. If the Action Code is "R" (Removed) or the NPI does not exist in esMD, and it is associated with a HIH OID.
6. Duplicate submission for the same HIH OID and NPI combination for Action Code "E" or "A". 		1. The NPI {0} received must be unique within the Registration Bundle Request.
{0} = NPI
2. Maximum of {0} Practitioner resources can be sent in the bundle request.
{0} = Count of NPIs
3. The NPI {0} received in the Registration Request for Action Code {1} is inactive or missing consent in the NPPES.
{0} = NPI
{1} = Action Code
4. The NPI {0} received in the Registration Request has incorrect value {1} for the NPPES consent. Correct value is 'CMS esMD eMDR' in the [useOtherDescription] field. Request provider to correct the consent and resubmit the request.
{0} = NPI
{1} = Value
5. The Action Code R received in the Registration Request is not allowed for NPI {0} as association with the HIH OID does not exist in esMD.
{0} = NPI
6. The HIH OID {0} and NPI {1} received for Action Code {2} is already registered with the submitting HIH or another HIH.
{0} = HIH OID
{1} = NPI
{2} = Action Code