Skip to main content

Accessing Patient Data

Once a patient chooses to share their health data with your organization, you have several options to access that data.

Data Delivery (Push)​

HealthEx supports having patient data "pushed" to your organization whenever a patient shares or updates their data. In this model, you are responsible for storing the patient data long-term within your organization's boundaries, and can access that data whenever you need to.

Data can be delivered through two mechanisms:

Amazon S3 Bucket​

Patient data can be uploaded to an Amazon S3 bucket of your choosing, within an AWS account that you control. Follow the steps below to configure the integration.

Step 1: Locate Your S3 Bucket Name​

  • Log in to the AWS Management Console.
  • Search for and open the S3 service.
  • In the list of buckets, find the bucket you created and copy its exact name (e.g., my-healthex-patient-data).

Step 2: Create a Custom IAM Permissions Policy​

  • In the AWS Console search bar, type IAM and open the IAM dashboard.
  • In the left navigation pane, click Policies, then click Create policy.
  • Select the JSON tab and replace the existing text with the following policy (replace YOUR-BUCKET-NAME-HERE with your actual bucket name):
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "HealthExWritePermissions",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME-HERE/*"
    }
  ]
}
  • Click Next.
  • Give your policy a name you will recognize, such as HealthExBucketWritePolicy.
  • Click Create policy.

Step 3: Create the IAM Role and Establish Trust​

Now you will create the IAM Role that HealthEx will "assume" to write data to your bucket.

  • In the left navigation pane of the IAM dashboard, click Roles, then click Create role.
  • Under Select type of trusted entity, select Custom trust policy.
  • Paste the following JSON into the Custom trust policy editor. This tells AWS that HealthEx's system account is allowed to use this role:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::549768250936:role/prod-us-west-2-backend-external-data-delivery-role"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
  • Click Next.
  • On the Add permissions page, search for the policy you created in Step 2 (HealthExBucketWritePolicy). Check the box next to it.
  • Click Next.
  • Give your role a clear name, such as HealthEx-Data-Delivery-Role.
  • Review the configuration and click Create role.

Step 4: Copy the Role ARN​

After creating the role, it should appear in your Roles list. If not, search for HealthEx-Data-Delivery-Role in the IAM Roles search bar and click on it.

Look for the ARN at the top of the Summary page. It will look like this:

arn:aws:iam::123456789012:role/HealthEx-Data-Delivery-Role

Copy this ARN string.

Step 5: Complete Configuration in HealthEx​

Sign in to Org > Admin > Data Settings and select Deliver patient data to an Amazon S3 bucket. Enter:

  • Bucket name: (From Step 1, e.g., my-healthex-patient-data)
  • Bucket region: AWS region of your bucket (e.g., us-east-2)
  • ARN of your IAM role: (From Step 4)
  • Path in bucket: Customize using available variables (see below)
Available Path Variables​

You can use any of these variables in your bucket path:

  • {orgId}: The unique ID of your organization in HealthEx
  • {projectId}: The unique ID of your HealthEx project
  • {referenceId}: The unique ID HealthEx has assigned the patient for your project
  • {externalId}: A unique ID that you have assigned the patient through our Add Patient API or a unique link
  • {retrievalId}: A unique ID representing this data retrieval. This changes every time the patient updates their data
  • {dataType}: The format type of the data: ccda or fhir
  • {timestamp}: The time that the data was delivered at (ISO 8601 format)

Example: /{projectId}/{referenceId}/{dataType}

Additional Settings​

Configure the following options:

  • Data Format: File format for delivered data
  • Data Compression: Compression method (if any)
  • Automated Background Data Refresh: Enable automatic periodic updates

Click Save to complete the configuration.

SFTP Server​

Patient data can be uploaded to any SFTP server that you control. Provide your server's connection details and configure the delivery path.

Step 1: Complete Configuration in HealthEx​

Sign in to Org > Admin > Data Settings and select Deliver patient data to an SFTP server. Enter:

  • SFTP Host: Your server's hostname or IP address
  • Port: Typically 22 (or your server's custom port)
  • Username: Your SFTP account username
  • Password: Your SFTP account password
  • Path on server: Customize using available variables (see below)
Available Path Variables​
  • orgId: the unique ID of your organization in HealthEx
  • projectId: the unique ID of your HealthEx project
  • referenceId: the unique ID HealthEx has assigned the patient for your project
  • externalId: a unique ID that you have assigned the patient through our Add Patient API or a unique link
  • retrievalId: a unique ID representing this data retrieval. This will change every time the patient updates their data
  • dataType: the format type of the data, ccda or fhir
  • timestamp: the time that the data was delivered at

Example: /{projectId}/{referenceId}/{dataType}

Additional Settings​

Configure the following options:

  • Data Format: File format for delivered data
  • Data Compression: Compression method (if any)
  • Automated Background Data Refresh: Enable automatic periodic updates

Data Query (Pull)​

HealthEx also supports your organization fetching data on-demand. In this model, you do not need to store patient data long-term, but rather call our APIs whenever you need a part of the patient's data.

HealthEx MCP Server​

HealthEx's Model Context Protocol server brings HealthEx directly into any AI agent workflow by implementing the MCP standard.

See the documentation for our MCP server

HealthEx FHIR APIs​

HealthEx's FHIR APIs allow you to fetch a patient's health data across a broad range of supported FHIR resource types.

See the documentation for our FHIR Server