Skip to main content

File upload

Allow respondents to upload documents and files via Awell Forms

Written by Awell Support

Awell Forms support collecting images and documents from respondents using the "File upload" or "Image upload" question types.

To start using these question types, you need to set up a File Storage configuration via the "Integrations" page in your organization. There are two options:

  1. Connect your own storage provider (e.g., Google Cloud Storage or Amazon S3) to store uploaded files in your preferred storage provider. This is the preferred way to handle file uploads as you retain control over the uploaded files.

  2. Let Awell handle storage (GCS) – if you don’t have a storage provider or prefer Awell to manage it, contact our Customer Success team for assistance.

Upload questions in the Form builder

Both the "File upload" and "Image upload" question types currently support only one file per question. For example, if you want a respondent to upload both sides of an ID card, you should use two separate questions—one for the front and one for the back.

For each upload question, you’ll need to select a File Storage destination—one of the configurations you've set up in "Integrations". You can also define which file types are allowed using file type specifiers.

Tip: You can use Shelly to help you out with some of this configuration, especially the file types!

Setting up File Storage

You can set up one or more File Storage configurations via the Integrations page in the Awell platform. Currently, only GCS is supported as a storage provider but Amazon S3 will be added soon.

Google Cloud Storage (GCS)

Step 1: Create the GCS bucket

Create the GCS bucket via the Google Cloud Console. Take note of the bucket name as you will have to enter the name of your bucket in Awell.

Step 2: Grant Awell write permissions to your bucket

Within your bucket, click Permissions and then Grant access and provide the Storage Object Creator and Storage Object User roles to Awell's Service Account user. This account is different per environment:

  1. Sandbox: [email protected]

  2. Production EU: [email protected]

  3. Production UK: [email protected]

  4. Production US: [email protected]

Step 3: CORS settings

Because Awell will upload files directly from the Browser (via Awell Care or Hosted Pages), you need to allow Cross-Origin Resource Sharing (CORS) for your bucket.

Please follow the instructions below:

  1. Install the Google Cloud SDK CLI: https://cloud.google.com/sdk/docs/install

  2. Login with 'gcloud init' command

  3. Create cors.json file with the below example config.

  4. Upload the CORS configuration with gsutil cors set cors.json gs://{ YOUR_BUCKET_NAME }

  5. You can confirm your CORS settings with gsutil cors get gs://{ YOUR_BUCKET_NAME }

[
  {
    "origin": ["*"],
    "responseHeader": ["*"],
    "method": ["PUT"],
    "maxAgeSeconds": 3600
  }
]

Step 4: Finalize the File Storage setup in Awell

Back in Awell, provide your bucket name, and a description of the bucket and save the File Storage configuration.

Once saved, you can select the File Storage destination you just created when configuring the question in the form builder.

Amazon S3

Step 1: Create the S3 bucket

Create the S3 bucket via the AWS Console. Take note of the bucket name as you will have to enter the name of your bucket in Awell.

Step 2: CORS settings

Because Awell will upload files directly from the Browser (via Awell Care or Hosted Pages), you need to allow Cross-Origin Resource Sharing (CORS) for your bucket. You should continue to block all public access to the bucket.

Please follow the instructions below:

  1. Navigate to the Permissions tab in your S3 bucket

  2. Scroll down to the "Cross-origin resource sharing (CORS)" section and edit the configuration

  3. Add the following configuration, specifying the domains for which you anticipate file uploads, or use * to allow all domains

[
  {
    "AllowedHeaders": [
      "*"
    ],
    "AllowedMethods": [
      "PUT"
    ],
    "AllowedOrigins": [
      "https://care.us.awellhealth.com",
      "https://hosted-pages.yourdomain.com"
    ],
    "ExposeHeaders": [
      "ETag"
    ],
    "MaxAgeSeconds": 3000
  }
]

Step 3: Create an IAM user with permissions to write to the bucket

Unless you'd like to use an existing IAM user, create a new IAM user and grant them, or their group, a policy to write items to the S3 bucket, replacing your-s3-bucket-name with your real bucket name:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AwellDirectUploads",
            "Effect": "Allow",
            "Action": "s3:PutObject",
            "Resource": "arn:aws:s3:::your-s3-bucket-name/*"
        }
    ]
}

Step 4: Generate Access key ID and Secret for the IAM user

Generate credentials that will be used in the Awell console.

  1. Navigate to the Security credentials tab for the IAM user

  2. Under Access keys, click "Create access key"

  3. Choose "Application running outside AWS" as the use case

  4. Give the key a description like "Awell direct upload"

  5. Click "Create access key"

  6. Keep this page open or copy the values for Access key and Secret access key

Step 5: Finalize the File Storage setup in Awell

Back in Awell, provide your bucket name, the region where you created the bucket, the Access key, the Secret access key, and a description of the bucket and save the File Storage configuration.

Once saved, you can select the File Storage destination you just created when configuring the question in the form builder.

File metadata

When a file is uploaded to your storage provider, its original filename is automatically prepended with a UNIX timestamp. Currently, no additional metadata is added to the uploaded file objects.

To keep your files organized, we recommend setting up multiple file bucket configurations. This allows you to route different file upload questions to separate buckets, making managing and maintaining a clear structure easier.

Need additional metadata or more advanced file organization? Reach out to our Customer Success team—we're happy to help!

Accessing uploaded files

Once a respondent uploads a file, you may want to make it accessible to other users or send it to a third-party system like an EHR. There are two common ways to do this:

  1. Reference by URL – When a file is uploaded to your storage bucket, Awell stores a reference (a URL) to the file. You can easily use this URL in your care flow or send it to external systems.

  2. Binary upload – If you need to upload the file's binary content directly to another system, please contact our Customer Success team for support so we can work together with you to find an appropriate solution and workflow.

Reference by URL

If your storage bucket is public, the file URLs stored by Awell can be accessed by anyone and easily shared with third-party systems.

If your bucket (or folder) is private but you still want to give users access—whether through Awell or another system—you’ll need to generate a signed URL. For help with this setup, please contact our Customer Success team so we can work together with you to find an appropriate solution and workflow.

Related Articles
Effortless Form Building with Shelly
Go-live Checklist
Did this answer your question?