How to Migrate from Azure API for FHIR to Azure Health Data Services

What happens if a production FHIR endpoint is still serving your healthcare applications on October 1, 2026? That is no longer a theoretical migration-planning question.

Microsoft is retiring Azure API for FHIR on September 30, 2026. After retirement, customers will no longer be able to create or manage Azure API for FHIR accounts, access their data through the Azure portal or APIs, SDKs, or client tools, receive service updates, or access customer support for the retired service.

For a U.S. healthcare organization, the risk goes beyond losing a cloud service.

The existing FHIR endpoint may sit behind EHR integrations, patient applications, payer APIs, SMART on FHIR applications, analytics pipelines, Azure Functions, integration engines, or population health workflows. You can successfully move every Patient, Encounter, and Observation resource and still have a failed migration if authentication, search behavior, networking, or downstream applications do not work against the new endpoint.

That is why a successful Azure API for FHIR migration must move four things together:

FHIR data, platform configuration, application connectivity, and production operations.

This guide explains how to migrate from Azure API for FHIR to the FHIR service in Azure Health Data Services, how to choose between lift-and-shift and incremental migration, where Microsoft’s FHIR migration tool fits, and what healthcare IT teams should validate before production cutover.

Azure API for FHIR Retirement Announcement: September 30, 2026

Microsoft formally announced the Azure API for FHIR retirement in September 2023.

The announcement established two key dates:

• April 1, 2025: New Azure API for FHIR deployments stopped being allowed.
• September 30, 2026: Azure API for FHIR retires.

Microsoft recommends migrating customers to the FHIR service in Azure Health Data Services, which it describes as the evolved platform for managed health data services on Azure.

The retirement date should not be treated as the date to begin migration.

It is the date before which healthcare organizations should have completed data migration, configuration, application remediation, validation, production cutover, and operational acceptance.

There is also a separate deadline that can affect SMART applications.

Microsoft says the SMART on FHIR Proxy retires on September 21, 2026. Applications still dependent on the proxy need to transition to Microsoft’s current SMART on FHIR approach before that date.

For organizations using both Azure API for FHIR and the legacy SMART proxy, that effectively creates two retirement workstreams.

What Changes When You Move to Azure Health Data Services?

The destination still exposes a standards-based FHIR API, but this is not simply an in-place upgrade or product rename.

Azure Health Data Services deploys the FHIR service inside an Azure Health Data Services workspace and introduces platform differences that can affect application behavior and architecture.

Microsoft’s current migration comparison highlights several changes:

Migration Area	Azure Health Data Services FHIR Service
Data ingestion	Native $import operation
Scaling	Autoscaling enabled by default
Bundle support	Batch and transaction
Search	Selectable search parameters, broader _include/_revinclude support and expanded sorting
Events	Built-in Events capability
Authorization	Microsoft Entra-based authorization; local RBAC/custom authority from Azure API for FHIR are not carried forward in the same model
Storage	4 TB default capacity per FHIR instance; higher capacity requires Azure Support
Infrastructure	Supports capabilities including customer-managed keys, PITR, and availability-zone support

The first migration question should therefore not be: How do we export the data? It should be: What currently depends on this FHIR environment?

13 Step Process to Migrate Azure API for FHIR to Azure Health Data Services

Step 1: Inventory the Entire Azure FHIR Dependency Chain

Start with a production dependency map. Look beyond applications that directly execute FHIR REST calls. Inventory:

• EHR integrations
• SMART on FHIR applications
• patient-facing applications
• payer and interoperability APIs
• integration engines
• Azure Functions and Logic Apps
• analytics and research pipelines
• $export jobs
• Blob Storage and Data Lake workflows
• US Core or other implementation guides
• custom FHIR profiles
• custom SearchParameter resources
• Microsoft Entra applications
• service principals
• managed identities
• FHIR RBAC assignments
• CORS settings
• private endpoints and Private Link
• DNS and firewall dependencies
• customer-managed keys
• audit-log destinations
• Event Grid integrations
• CI/CD variables
• secrets or Key Vault references containing the old FHIR URL

This matters because Microsoft’s OSS migration tool only migrates FHIR resources. It does not automatically migrate server configuration, and the destination FHIR service receives a new endpoint. Applications must therefore be repointed and relevant settings rebuilt or reconfigured.

A resource-count match does not prove operational readiness.

Step 2: Build the Azure Health Data Services Target First

Provision the destination before production data movement begins.

Microsoft’s migration sequence calls for deploying an Azure Health Data Services workspace and then deploying the FHIR service within that workspace. Configuration should be prepared before migration rather than deferred until cutover.

Validate several architecture decisions first.

Confirm the Azure Region

For U.S. workloads, Microsoft currently lists the FHIR service in:

• East US
• East US2
• South Central US
• North Central US
• West Central US
• West US2
• West US3

However, other Azure Health Data Services capabilities do not have identical regional availability. For example, Events is currently listed in East US and East US2 but not every U.S. FHIR region. Confirm the complete target architecture rather than checking only FHIR availability.

Confirm Storage Requirements

Azure Health Data Services FHIR instances have a default 4 TB storage limit. Microsoft instructs customers requiring more than 4 TB to submit an Azure Support request for additional capacity.

A separate threshold applies to the migration itself.

If the existing Azure API for FHIR instance contains more than 2 TB, Microsoft recommends opening an Azure Support request before migration and providing both the source and destination service names.

Do not confuse the two thresholds:

More than 2 TB source: engage Microsoft for migration planning.

More than 4 TB destination: request increased AHDS FHIR capacity.

Confirm the FHIR Version

Azure Health Data Services supports FHIR STU3 and R4. If your current environment is STU3, decide whether this project is:

a platform migration

or

a platform migration plus an STU3-to-R4 transformation.

Those are different scopes.

Step 3: Separate Infrastructure Migration From STU3-to-R4 Conversion

Do not quietly introduce a FHIR-version conversion into the migration without treating it as its own validation workstream.

Microsoft documents $convert-data support for:

• HL7v2 to FHIR R4
• C-CDA to FHIR R4
• JSON to FHIR R4
• FHIR STU3 to FHIR R4

But Microsoft also cautions that its STU3-to-R4 Liquid templates primarily map field differences. Some STU3 resources were renamed or removed in R4, and converted data may require additional validation and processing.

For a healthcare organization with many production consumers, changing both the hosting platform and FHIR version in one cutover increases testing scope.

Where appropriate, migrate the platform first while preserving the current FHIR version. Modernize the specification separately after the new environment is stable.

Step 4: Rebuild Identity, Authorization, and SMART Configuration

FHIR data does not carry the access-control model with it.

Microsoft specifically instructs customers to change application endpoints and set up application permissions again when moving workloads to the new FHIR service.

Review and reconfigure as required:

• Microsoft Entra application registrations
• service principals
• managed identities
• FHIR RBAC assignments
• application scopes and audiences
• SMART authorization
• CORS
• customer-managed keys
• versioning policy
• export storage
• diagnostic settings

Do not assume every Microsoft Entra application registration must be recreated. Existing registrations may be reusable depending on the architecture. What must be verified is whether their configuration, audience, permissions, RBAC, endpoint references, and SMART behavior remain correct for the destination.

Microsoft also recommends comparing the /metadata capability statements of the old and new FHIR servers when validating configuration and behavior.

[/vc_column_text][/vc_column][/vc_row]

Step 5: Choose the Right Azure FHIR Migration Pattern

Microsoft documents two primary patterns.

Option 1: Lift and Shift With $export and $import

This is the simpler approach when a longer controlled downtime window is acceptable.

The workflow is:

Azure API for FHIR → $export → Azure Storage → $import → AHDS FHIR service

FHIR bulk export produces data that can be used for bulk migration, while the AHDS $import operation supports high-throughput ingestion of NDJSON resources.

The cutover pattern generally becomes:

Control writes → final export → import → validate → repoint applications → resume production.

The advantage is simplicity.

The downside is the downtime required while the final source state is being exported, imported, and verified.

Option 2: Incremental Migration With Microsoft’s OSS FHIR Migration Tool

For large repositories or organizations that want Azure API for FHIR to remain active while most data is copied, Microsoft’s open-source migration tool provides a continuous-copy model.

The tool is built on Azure Durable Functions and orchestrates $export from Azure API for FHIR and $import into Azure Health Data Services. It continuously moves newer data until the organization is ready for its final cutover window.

The sequence becomes:

Initial migration → incremental synchronization → target validation → source write freeze → final synchronization → cutover.

Microsoft’s tool documentation explicitly says the source can continue receiving writes, updates, and soft deletes during incremental migration. Before final cutover, writes should stop, and the remaining export/import cycles should complete.

This reduces downtime.

It does not eliminate the need for a controlled final write-freeze window.

Step 6: Configure the Migration Tool Correctly

Several prerequisites are easy to overlook.

Use Incremental $import

The destination must use incremental import mode when running Microsoft’s migration tool. Microsoft’s import documentation says incremental mode supports periodic loading without blocking normal API writes and can preserve lastUpdated and versionId when supplied in resource metadata.

Use the Same Storage Account for Export and Import

Microsoft requires the storage account configured as the Azure API for FHIR $export location to also be configured as the AHDS $import location for the migration tool.

Cross-Subscription Migration Needs Careful Validation

The current Microsoft migration tool explicitly says the source and destination can exist in the same subscription or different subscriptions, provided they belong to the same Microsoft Entra tenant and the same storage account is configured for export and import.

However, the repository’s appendix still contains an older troubleshooting entry stating that the two FHIR servers should be in the same subscription.

Because Microsoft’s own repository contains this inconsistency, cross-subscription deployments should be tested against the current migration-tool release in a non-production environment. For high-risk migrations, confirm the supported configuration with Microsoft before production execution.

Step 7: Prepare Profiles and Search Parameters Before Moving Production Data

Healthcare applications do not simply depend on resource existence. They depend on how those resources can be searched and validated.

If your organization uses an implementation guide such as US Core, Microsoft’s current migration-tool instructions say to load the required profiles and associated search parameters into the destination before migration and complete the related reindex operation.

For custom search parameters that are not part of a standard implementation guide, Microsoft provides a Search Parameter Migration script.

The recommended sequence is:

1. Deploy required implementation guides and profiles.
2. Make sure their search parameters are available.
3. Run and complete the required $reindex.
4. Run the custom Search Parameter Migration script where applicable.
5. Allow the script-triggered destination reindex to finish.
6. Only then deploy and start the migration tool.

This is important because an application can fail even when all expected Patient or Observation resources exist. For example, test production queries such as:

• Patient identifier searches
• Encounter date searches
• Observation code searches
• chained searches
• _include
• _revinclude
• pagination
• custom SearchParameter queries
• transaction bundles

The target needs to reproduce the behavior expected by dependent applications, not merely the data volume.

Step 8: Check Data for Import-Specific Failures

One migration edge case deserves special attention. Microsoft’s current migration-tool documentation warns that Azure Health Data Services supports up to 18 digits of precision for the FHIR decimal data type, while Azure API for FHIR did not enforce the same restriction.

FHIR resources containing decimal values with greater precision can therefore fail during $import. Microsoft documents an optional transformation step in its migration tooling for modifying such values before import. Do not automatically truncate clinical values simply to make an import succeed. Instead:

1. Identify affected resources before production migration.
2. Determine why the source contains over-precision values.
3. Define an approved transformation rule.
4. Validate the resulting clinical meaning.
5. Document the change for migration reconciliation.

For healthcare data, a technically successful import is not sufficient if transformation changes the intended meaning of the clinical record.

Step 9: Account for Private Link and Event-Driven Architectures

Private Link

If the environment uses Azure Private Link, Microsoft’s migration tool requires the separate Private Link deployment path. Microsoft states that Private Link environments must use the manual migration-tool deployment option rather than the standard Azure portal deployment flow.

That should be designed before migration day because routing, private DNS, Function App connectivity, and storage access can all affect tool execution.

Event Grid and FHIR Events

Microsoft’s migration tool writes source exports into a storage container called Migration.

If Event Grid currently monitors the source $export storage account, Microsoft recommends excluding that Migration container so migration exports do not trigger existing event-processing workflows.

The repository also recommends leaving eventing disabled on the destination FHIR service while migration is running and enabling destination eventing after cutover.

For event-driven interoperability architectures, this prevents migration traffic from being mistaken for production clinical events.

Step 10: Validate the Migration at Three Levels

A migration job reaching 100% is not enough.

1. Resource-Level Validation

Compare resources by type.

Microsoft’s tooling supports both surface and deeper migration checks. At minimum, validate counts and sampled resource content for high-value resource types such as:

• Patient
• Encounter
• Condition
• Observation
• MedicationRequest
• DiagnosticReport
• Procedure
• AllergyIntolerance
• DocumentReference

Where required, validate:

• resource IDs
• references
• identifiers
• extensions
• meta.lastUpdated
• version history
• soft-delete behavior

2. API-Level Validation

Run the operations the applications actually use. Test:

• authentication
• RBAC
• SMART launch
• searches
• paging
• creates
• updates
• conditional operations
• transaction bundles
• custom SearchParameter behavior
• $export
• downstream jobs

Do not restrict technical validation to:

GET /Patient

and

GET /metadata.

3. Workflow-Level Validation

Finally, test business and interoperability workflows.

• Can the patient application retrieve records?
• Can an EHR-connected SMART application launch?
• Can an external integration locate the expected patient?
• Can a payer API retrieve the required resources?
• Can the analytics pipeline complete its bulk export?
• Can a new Observation reach downstream consumers correctly?

That is where a technically complete data migration becomes a production-ready healthcare migration.

Step 11: Reconcile Hard Deletes Before Cutover

Incremental migration handles new resources, updates, and soft deletes differently from hard deletes.

Microsoft states that a FHIR resource hard-deleted from the source after the initial migration is not automatically removed from the destination. Those deletes need to be tracked and reconciled manually.

Build delete reconciliation into the runbook.

Otherwise, the new FHIR environment can contain resources intentionally removed from the source during the migration period.

Step 12: Execute a Controlled Production Cutover

When most data is synchronized and testing is complete, execute the final cutover as a controlled change. A practical sequence is:

1. Stop source writes.
2. Allow the final incremental export/import cycles to finish.
3. Review migration failures.
4. Reconcile hard deletes.
5. Run final resource validation.
6. Change application endpoints.
7. Confirm application permissions and RBAC.
8. Validate SMART workflows.
9. Run interoperability smoke tests.
10. Enable required destination eventing.
11. Monitor production traffic.
12. Obtain technical and application-owner acceptance.
13. Decommission the source only after migration evidence is complete.

Microsoft likewise recommends stopping source writes before the last incremental copy and repointing applications only after the destination is ready.

Avoid introducing unnecessary simultaneous changes.

Changing the FHIR version, authentication model, application code, network architecture, and business workflows during one cutover makes troubleshooting much harder.

Step 13: Enable FHIR Audit Logging Before Hypercare

Do not wait for a production incident to configure visibility. For the Azure Health Data Services FHIR service, Microsoft documents AuditLogs through Azure diagnostic settings. They can be sent to:

• Log Analytics
• Azure Storage
• Event Hub
• Supported partner solutions

FHIR audit-log fields can include caller identity, caller IP, FHIR resource type, operation, request URI, status, HTTP status code, correlation ID, and tenant information. During hypercare, watch for:

• HTTP 401 authentication errors
• HTTP 403 authorization failures
• unexpected 404s
• failed writes
• search mismatches
• application retries
• integration failures
• unusual request patterns

Migration is complete when the production ecosystem is stable, not when the data-copy process ends.

Azure FHIR Migration Is an Interoperability Cutover, Not Just a Data Copy

Azure API for FHIR and Azure Health Data Services both use FHIR.

That does not make migration automatic.

The complexity sits around the API: identity, search parameters, SMART authorization, export jobs, profiles, eventing, Private Link, application endpoints, and downstream clinical or administrative workflows.

The safest migration sequence is:

Discover → Design → Configure → Prepare → Migrate → Validate → Cut Over → Monitor.

Microsoft provides the destination platform, $export, $import, and an OSS incremental migration tool. 

The healthcare organization’s responsibility is to make sure those capabilities are integrated into a migration plan that preserves data integrity and keeps dependent applications working.

That is ultimately what determines whether an Azure API for FHIR migration is successful.

Need Help Planning Your Azure FHIR Migration?

CapMinds helps healthcare organizations assess existing FHIR dependencies, design Azure Health Data Services environments, migrate FHIR data, rebuild interoperability workflows, validate integrations, and plan controlled production cutovers.

If Azure API for FHIR is still supporting active EHR, payer, patient-access, SMART, analytics, or interoperability workloads, start by mapping what depends on the current endpoint.

Review Your Azure FHIR Migration Plan