Practitioner API

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

Overview
API Information
- Endpoints:
Request Headers
Sample Practitioner Request

Overview

The Practitioner API facilitates secure management of practitioner data within the esMD system. This API enables HIHs to submit, update, and manage practitioner details using FHIR-compliant JSON payloads.

The Practitioner API supports the single provider registration method where a single provider is registered using one request.

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}

API Information

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

Endpoints:

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

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

↑ Back to top

Sample Practitioner Request

PUT /api/esmdf/ext/v1/fhir/Practitioner/{id} HTTP/1.1
Host: dev.cpiapigateway.cms.gov
Authorization: Bearer {token}
Content-Type: application/fhir+json
Accept: application/fhir+json

{
    "resourceType": "Practitioner",
    "id": "PRACT123",
    "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"
            }
        ]
    },
    "name": [
        {
            "family": "Gaven",
            "given": [
                "Radems"
            ],
            "prefix": [
                "Dr"
            ],
            "suffix": [
                "Ph.D"
            ]
        }
    ],
    "telecom": [
        {
            "system": "phone",
            "value": "551-333-6141",
            "use": "work"
        }
    ],
    "address": [
        {
            "use": "work",
            "line": [
                "1003 MILLERS DR"
            ],
            "city": "ELLICOTT CITY",
            "state": "MD",
            "postalCode": "21043"
        }
    ],
    "gender": "female",
    "active": true,
    "extension": [
        {
            "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-NPI",
            "valueString": "1700962487"
        },
        {
            "url": "https://terminology.esmduat.cms.gov:8099/fhir/StructureDefinition/Esmd-Ext-ProviderTaxId",
            "valueString": "101-56-55"
        },
        {
            "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": "2026-12-30"
        }
    ]
}

↑ Back to top