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/$everything  start 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. HealthLake supports FHIR $export using POST and GET requests. To make an export request with POST, you must have a IAM user, group, or role with the required permissions, specify $export as part of the request, and include desired parameters in the request body.

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

Before you begin

Meet the following requirements to make an export request 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 using either IAM or OAuth2.0. You must also have a service role.

Authorizing a request using IAM

When you make an $export request, the user, group, or role must have IAM actions included in the policy. For more information, see Setting up permissions for export jobs.

Authorizing a request using SMART on FHIR (OAuth 2.0)

When you make an $export request on a SMART on FHIR-enabled HealthLake data store, you must have the appropriate scopes assigned. For more information, see SMART on FHIR resource scopes for HealthLake.

Making an $export request

This section describes the required steps you must take when making an export request 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 where 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://amzn-s3-demo-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 the request 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 using the REST API, you are only 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://amzn-s3-demo-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",
  }
}