FHIR R4 operations for HealthLake

AWS HealthLake supports the following FHIR REST API operations.

Getting patient data with Patient/$everything

The Patient/$everything operation is used to query a FHIR Patient resource, along with any other resources related to that Patient. The operation can be used to provide a patient with access to their entire record or for a provider to perform a bulk data download related to a patient. HealthLake supports Patient/$everything for a specific patient id.

Patient/$everything is a FHIR REST API operation that can be invoked as shown in the examples below.

Patient/$everything parameters

HealthLake supports the following query parameters

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?start=2024-03-15T00:00:00.000Z

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?end=2024-03-15T00:00:00.000Z

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?since=2024-03-15T00:00:00.000Z

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_type=Observation,Condition

GET https://healthlake.region.amazonaws.com/datastore/datastoreId/r4/Patient/id/$everything?_count=15

Patient/$everythingstart and end attributes

HealthLake supports the following resource attributes for the Patient/ $everything start and end query parameters.

Exporting HealthLake data with FHIR $export

You can export data in bulk from your HealthLake data store using the FHIR $export operation. To make an export request, 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.

You can queue export requests per the AWS account service quotas. For more information, see Service 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 must also 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 must 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.

You can use the following supported search parameters in the POST request string.

Supported search parameters

HealthLake supports the following search modifiers in bulk export requests.

The following 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 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.region.amazonaws.com/datastore/datastoreId/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.region.amazonaws.com/datastore/datastoreId/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.region.amazonaws.com/datastore/datastoreId/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",
  }
}