Before you begin Authorizing an export request Making an export request Managing your export request

Exporting data from your data store by using the FHIR REST API

Important

HealthLake data stores created prior to June 1, 2023 only support FHIR REST API based export job requests for system-wide exports.

HealthLake data stores created prior to June 1, 2023 do not support getting the status of an export using a GET request on a data store's endpoint.

To make an export request using the FHIR REST API, you must have a IAM user, group, or role with the required permissions, specify $export as part of the POST request, and include request parameters in the body of your request. According to the FHIR specification, the FHIR server must support GET requests, and can support POST requests. In order to support additional parameters, a body is needed to start the export, therefore HealthLake supports POST requests.

All export requests you make using the FHIR REST API are returned in ndjson format and exported to an Amazon S3 bucket. Each S3 object will contain only a single FHIR resource type.

You can queue export requests as per the AWS account quotas. To learn more about the Service Quotas associated with HealthLake, see AWS HealthLake endpoints and quotas.

HealthLake supports the following three types of bulk export endpoint requests.

Type	Descriptions	Syntax
System export	Export all data from the HealthLake FHIR server.	`POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/$export`
All patients	Export all data relating to all patients including resource types associated with the Patient resource type.	`POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/$export`
Group of Patients	Export all data relating to a group of patients specified with a Group ID.	`POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Group/ID/$export`

Before you begin

Meet the following requirements to make an export request by using the FHIR REST API for HealthLake.

You must have set up a user, group, or role that has the necessary permissions to make the export request. To learn more, see Authorizing an export request.
You must have created a service role that grants HealthLake access to the Amazon S3 bucket to which you want your data to be exported. The service role must also specify HealthLake as the service principal. To learn more, see Creating a service role.

Authorizing an `export` request

To make a successful export request using the FHIR REST API, authorize your user, group, or role m by using either IAM or OAuth2.0. You also must have a service role.

Authorizing a request by using IAM

When you make an $export request, the user, group, or role must have StartFHIRExportJobWithPost, DescribeFHIRExportJobWithGet, and CancelFHIRExportJobWithDelete IAM actions included in the policy.

Authorizing a request using SMART on FHIR (OAuth 2.0)

When you make an $export request on SMART on FHIR enabled HealthLake data store, you need to have the appropriate scopes assigned. To learn more about supported scopes, see HealthLake data store FHIR resource specific scopes.

Making an `export` request

This section describes the required steps you must take when making an export request by using the FHIR REST API.

To avoid accidental charges on your AWS account, we recommend testing your requests by making a POST request without supplying the export syntax.

To make the request, you must do the following:

Specify export in the POST request URL for a supported endpoint.
Specify the required header parameters.
Specify a request body that defines the required parameters.

Step 1: Specify `export` in the `POST` request URL for a supported endpoint

HealthLake supports three types of bulk export endpoint requests. To make a bulk export request, you must make a POST-based request on one of the three supported endpoints. The following examples demonstrate how to specify export in the request URL.

POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/$export
POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Patient/$export
POST https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/Group/ID/$export

In that POST request string, you can use the following supported search parameters.

Supported search parameters

HealthLake supports the following search modifiers in bulk export requests.

These examples include special characters which must be encoded prior to submitting your request.

Name	Required?	Description	Example
`_outputFormat`	No	The format for the requested Bulk Data files to be generated. Accepted values are `application/fhir+ndjson`, `application/ndjson`, `ndjson`.
`_type`	No	A string of comma delimited FHIR resource types that you want included in your export job. We recommend including `_type` because this can have a cost implication when all resources are exported.	`&_type=MedicationStatement, Observation`
`_since`	No	Resource types modified on or after the date time stamp. If a resource type does not have a last updated time they will be included in your response.	`&_since=2024-05-09T00%3A00%3A00Z`

Step 2: Specify the required header parameters

To make an export request using the FHIR REST API, you must specify the following two header parameters.

Content-Type: application/fhir+json
Prefer: respond-async

Next, you must specify the required elements in the request body.

Step 3: Specify a request body the defines the required parameters.

The export request also requires a body in JSON format. The body can include the following parameters.

To learn more, see Creating a service role

Key	Required?	Description	Value
DataAccessRoleArn	Yes	An ARN of a HealthLake service role. The service role used must specify HealthLake as the service principal.	`arn:aws:iam::444455556666:role/your-healthlake-service-role`
JobName	No	The name of the export request.	`your-export-job-name`
S3Uri	Yes	Part of an OutputDataConfig key. The S3 URI of the destination bucket where your exported data will be downloaded.	`s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB/`
KmsKeyId	Yes	Part of an OutputDataConfig key. The ARN of the AWS KMS key used to secure the Amazon S3 bucket.	`arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab`

Example – Body of an export request made by using the FHIR REST API

To make an export request by using the FHIR REST API, you must specify a body, as shown in the following.


{
  "DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
  "JobName": "your-export-job",
  "OutputDataConfig": {
    "S3Configuration": {
      "S3Uri": "s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB",
      "KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"
    }
  }
}

When your request is successful, you will receive the following response.

Response Header


content-location: https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/export/your-export-request-job-id

Response Body


{
  "datastoreId": "your-data-store-id",
  "jobStatus": "SUBMITTED",
  "jobId": "your-export-request-job-id"
}

Managing your export request

After making a successful export request, you can manage that request by using export to describe the status of a current export request, and export to cancel a current export request.

When you cancel an export request by using the REST API, you will only be billed for the portion of the data that was exported up to the time you submitted the cancel request.

The following topics describe how you can get the status on or cancel a current export request.

Canceling an export request

To cancel an export request, make a DELETE request and supply the job ID in the request URL.


DELETE https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/export/your-export-request-job-id

When your request is successful, you receive the following.


{
  "exportJobProperties": {
    "jobId": "your-original-export-request-job-id",
    "jobStatus": "CANCEL_SUBMITTED",
    "datastoreId": "your-data-store-id"
  }
}

When your request is not successful, you receive the following.


{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-supported",
      "diagnostics": "Interaction not supported."
    }
  ]
}

Describing an export request

To get the status of an export request, make a GET request by using export and your export-request-job-id.


GET https://healthlake.your-region.amazonaws.com/datastore/your-datastore-id/r4/export/your-export-request-id

The JSON response will contain an ExportJobProperties object. It may contain the following key:value pairs.

Name	Required?	Description	Value
DataAccessRoleArn	No	An ARN of a HealthLake service role. The service role used must specify HealthLake as the service principal.	`arn:aws:iam::444455556666:role/your-healthlake-service-role`
SubmitTime	No	The date time an export job was submitted.	`Apr 21, 2023 5:58:02`
EndTime	No	The time an export job was completed.	`Apr 21, 2023 6:00:08 PM`
JobName	No	The name of the export request.	`your-export-job-name`
JobStatus	No		Valid values are: `SUBMITTED \| IN_PROGRESS \| COMPLETED_WITH_ERRORS \| COMPLETED \| FAILED`
S3Uri	Yes	Part of an OutputDataConfig object. The Amazon S3 URI of the destination bucket where your exported data will be downloaded.	`s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB/`
KmsKeyId	Yes	Part of an OutputDataConfig object. The ARN of the AWS KMS key used to secure the Amazon S3 bucket.	`arn:aws:kms:region-of-bucket:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab`

Example : Body of a describe export request made using the FHIR REST API

When successful, you will get the following JSON response.


{
  "exportJobProperties": {
    "jobId": "your-export-request-id",
    "JobName": "your-export-job",
    "jobStatus": "SUBMITTED",
    "submitTime": "Apr 21, 2023 5:58:02 PM",
    "endTime": "Apr 21, 2023 6:00:08 PM",
    "datastoreId": "your-data-store-id",
    "outputDataConfig": {
      "s3Configuration": {
        "S3Uri": "s3://DOC-EXAMPLE-DESTINATION-BUCKET/EXPORT-JOB",
        "KmsKeyId": "arn:aws:kms:region-of-bucket:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab""
      }
    },
    "DataAccessRoleArn": "arn:aws:iam::444455556666:role/your-healthlake-service-role",
  }
}

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

SDK based export

FHIR REST API reference