Export FHIR data in Azure API for FHIR

Important

Azure API for FHIR will be retired on September 30, 2026. Follow the migration strategies to transition to Azure Health Data Services FHIR service by that date. Due to the retirement of Azure API for FHIR, new deployments won't be allowed beginning April 1, 2025. Azure Health Data Services FHIR service is the evolved version of Azure API for FHIR that enables customers to manage FHIR, DICOM, and MedTech services with integrations into other Azure services.

The Bulk Export feature allows data to be exported from the FHIR Server per the FHIR specification.

Before using $export, you'll want to make sure that the Azure API for FHIR is configured to use it. For configuring export settings and creating Azure storage account, refer to the configure export data page.

Using $export command

After configuring the Azure API for FHIR for export, you can use the $export command to export the data out of the service. The data will be stored into the storage account you specified while configuring export. To learn how to invoke $export command in FHIR server, read documentation on the HL7 FHIR $export specification.

Jobs stuck in a bad state

In some situations, there’s a potential for a job to be stuck in a bad state. This can occur especially if the storage account permissions haven’t been set up properly. One way to validate if your export is successful is to check your storage account to see if the corresponding container (that is, ndjson) files are present. If they aren’t present, and there are no other export jobs running, then there’s a possibility the current job is stuck in a bad state. You should cancel the export job by sending a cancellation request and try requeuing the job again. Our default run time for an export in bad state is 10 minutes before it will stop and move to a new job or retry the export.

The Azure API For FHIR supports $export at the following levels:

• System: GET https://<<FHIR service base URL>>/$export>>
• Patient: GET https://<<FHIR service base URL>>/Patient/$export>>
• Group of patients* - Azure API for FHIR exports all related resources but doesn't export the characteristics of the group: GET https://<<FHIR service base URL>>/Group/[ID]/$export>>

With export, data is exported in multiple files each containing resources of only one type. The number of resources in an individual file will be limited. The maximum number of resources is based on system performance. It is currently set to 5,000, but can change. The result is that you may get multiple files for a resource type, which will be enumerated (for example, Patient-1.ndjson, Patient-2.ndjson).

Note

Patient/$export and Group/[ID]/$export may export duplicate resources if the resource is in a compartment of more than one resource, or is in multiple groups.

In addition, checking the export status through the URL returned by the location header during the queuing is supported along with canceling the actual export job.

Exporting FHIR data to ADLS Gen2

Currently we support $export for ADLS Gen2 enabled storage accounts, with the following limitation:

• User can’t take advantage of hierarchical namespaces, yet there isn't a way to target export to a specific subdirectory within the container. We only provide the ability to target a specific container (where we create a new folder for each export).
• Once an export is complete, we never export anything to that folder again, since subsequent exports to the same container will be inside a newly created folder.

Settings and parameters

Headers

There are two required header parameters that must be set for $export jobs. The values are defined by the current $export specification.

• Accept - application/fhir+json
• Prefer - respond-async

Query parameters

The Azure API for FHIR supports the following query parameters. All of these parameters are optional:

Query parameter	Defined by the FHIR Spec?	Description
_outputFormat	Yes	Currently supports three values to align to the FHIR Spec: application/fhir+ndjson, application/ndjson, or just ndjson. All export jobs will return ndjson and the passed value has no effect on code behavior.
_since	Yes	Allows you to only export resources that have been modified since the time provided
_type	Yes	Allows you to specify which types of resources will be included. For example, _type=Patient would return only patient resources
_typefilter	Yes	To request finer-grained filtering, you can use _typefilter along with the _type parameter. The value of the _typeFilter parameter is a comma-separated list of FHIR queries that further restrict the results
_container	No	Specifies the container within the configured storage account where the data should be exported. If a container is specified, the data will be exported into a folder into that container. If the container isn’t specified, the data will be exported to a new container.
_till	No	Allows you to only export resources that have been modified till the time provided. This parameter is applicable to only System-Level export. In this case, if historical versions have not been disabled or purged, export guarantees true snapshot view, or, in other words, enables time travel.

Note

Only storage accounts in the same subscription as that for Azure API for FHIR are allowed to be registered as the destination for $export operations.

Secure Export to Azure Storage

Azure API for FHIR supports a secure export operation. Choose one of the two options below:

• Allowing Azure API for FHIR as a Microsoft Trusted Service to access the Azure storage account.

• Allowing specific IP addresses associated with Azure API for FHIR to access the Azure storage account. This option provides two different configurations depending on whether the storage account is in the same location as, or is in a different location from that of the Azure API for FHIR.

Allowing Azure API for FHIR as a Microsoft Trusted Service

Select a storage account from the Azure portal, and then select the Networking blade. Select Selected networks under the Firewalls and virtual networks tab.

Important

Ensure that you’ve granted access permission to the storage account for Azure API for FHIR using its managed identity. For more information, see Configure export setting and set up the storage account.

Under the Exceptions section, select the box Allow trusted Microsoft services to access this storage account and save the setting.

You're now ready to export FHIR data to the storage account securely. Note that the storage account is on selected networks and isn’t publicly accessible. To access the files, you can either enable and use private endpoints for the storage account, or enable all networks for the storage account for a short period of time.

Important

The user interface will be updated later to allow you to select the Resource type for Azure API for FHIR and a specific service instance.

Allowing specific IP addresses from other Azure regions to access the Azure storage account

In the Azure portal, go to the ADLS Gen2 account and select the Networking blade.

Select Enabled from selected virtual networks and IP addresses. Under the Firewall section, specify the IP address in the Address range box. Add IP ranges to allow access from the internet or your on-premises networks. You can find the IP address in the table below for the Azure region where the FHIR service is provisioned.

Azure Region	Public IP Address
Australia East	20.53.44.80
Canada Central	20.48.192.84
Central US	52.182.208.31
East US	20.62.128.148
East US 2	20.49.102.228
East US 2 EUAP	20.39.26.254
Germany North	51.116.51.33
Germany West Central	51.116.146.216
Japan East	20.191.160.26
Korea Central	20.41.69.51
North Central US	20.49.114.188
North Europe	52.146.131.52
South Africa North	102.133.220.197
South Central US	13.73.254.220
Southeast Asia	23.98.108.42
Switzerland North	51.107.60.95
UK South	51.104.30.170
UK West	51.137.164.94
West Central US	52.150.156.44
West Europe	20.61.98.66
West US 2	40.64.135.77

Allowing specific IP addresses to access the Azure storage account in the same region

The configuration process for IP addresses in the same region is just like above except a specific IP address range in Classless Inter-Domain Routing (CIDR) format is used instead (i.e., 100.64.0.0/10). The reason why the IP address range (100.64.0.0 – 100.127.255.255) must be specified is because an IP address for the FHIR service will be allocated each time an operation request is made.

Note

It is possible that a private IP address within the range of 10.0.2.0/24 may be used, but there is no guarantee that the operation will succeed in such a case. You can retry if the operation request fails, but until an IP address within the range of 100.64.0.0/10 is used, the request will not succeed. This network behavior for IP address ranges is by design. The alternative is to configure the storage account in a different region.

Next steps

In this article, you've learned how to export FHIR resources using $export command. Next, to learn how to export de-identified data, see

Export de-identified data

FHIR® is a registered trademark of HL7 and is used with the permission of HL7.