Exporting data from your HealthLake data store with FHIR REST API operations

After you complete Setting up permissions for export jobs, you can export data from your HealthLake data store with FHIR REST API operations. 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.

Before you begin

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

Authorizing an export request

To make a successful export request using the FHIR REST API, authorize your user, group, or role 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:

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.

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.

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.

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.

{
  "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.

SUBMITTED | IN_PROGRESS | COMPLETED_WITH_ERRORS | COMPLETED |
      FAILED

{
  "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",
  }
}