AWS S3 Integration

DocSpring’s AWS S3 integration automatically copies generated PDFs and Word documents into an S3 bucket in your own AWS account, giving you full control over your document storage. It also works with S3-compatible storage such as Cloudflare R2, Google Cloud Storage, Backblaze B2, Wasabi, DigitalOcean Spaces and MinIO.

Step-by-Step Implementation GuideComplete setup instructions for AWS S3 integration

Key Features

• Automatic uploads - PDFs are uploaded immediately after generation
• Flexible path templates - Organize PDFs using custom folder structures
• Selective uploads - Choose what to upload based on submission type, template, folder or API token, upload PDFs, Word documents or both, and skip combined PDFs
• Secure authentication - Support for both access keys and IAM roles
• No vendor lock-in - Keep your own copy of all generated documents

How It Works

1. Generate PDF - Create a submission through the API or web interface
2. Process - DocSpring generates the PDF from your template
3. Upload - PDF is automatically uploaded to your S3 bucket
4. Verify - Check the submission’s actions array to confirm upload

Note

DocSpring continues to store your PDFs for serving download URLs and combining submissions. The S3 integration provides an additional copy in your own infrastructure.

Configuration Options

Authentication Methods

• Access Key Authentication - Traditional IAM user with access keys
• Role-based Authentication - Secure cross-account role assumption (recommended)

Upload Filtering

Control what is uploaded to your bucket:

• Submission Type

  • Only Live (default) - Production PDFs without watermarks
  • Only Test - Development PDFs with watermarks
  • Both Live and Test - All PDFs

  Combined PDFs are uploaded with every setting.

• API Token IDs

  • Limit uploads to specific API tokens
  • Useful for environment separation (dev, staging, production)
  • Submissions created without an API token (for example from the dashboard or a web form) are still uploaded

• Template IDs and Folder IDs

  • Limit submission uploads to some templates, or to the templates in some folders (including their subfolders)
  • Leave both blank to upload submissions for every template
  • Combined PDFs aren’t filtered by template or folder

• File Formats

  • Word documents (.docx), OpenDocument files (.odt), PDFs, or All files (default)
  • A Word template’s submission has a Word document, an OpenDocument file (.odt) or both, and a PDF too when the template makes one. A submission that made none of the chosen files uploads nothing.
  • Combined PDFs are uploaded with PDFs and All files
  • An integration created before this setting was added uploads PDFs only, so its object keys ending in .pdf stay right: add {{ extension }} to its object key templates before you change it

• Object key templates

  • Leave an object key template blank to skip that kind of upload: for example, clear “Object Key Template for Combined PDFs” to upload submissions but not combined PDFs

Path Templates

Organize your files using Liquid template variables:

# Default templates
live/templates/{{ template_id }}/{{ submission_id }}.{{ extension }}
test/templates/{{ template_id }}/{{ submission_id }}.{{ extension }}
combined_submissions/{{ combined_submission_id }}.{{ extension }}

# Custom examples
{{ year }}/{{ month }}/{{ template_name }}/{{ submission_id }}.{{ extension }}
clients/{{ metadata.client_id }}/invoices/{{ submission_id }}.pdf

{{ extension }} is each file’s extension, pdf, docx or odt. With All files, the submission templates need it, so a submission’s files each get their own key. With Word documents or OpenDocument files only, a template can end in .docx or .odt instead.

Available VariablesThe full list of variables you can use in path templates

S3-compatible storage

The S3 integration can upload to any storage service with an S3-compatible API. When you create the integration, choose your provider under Storage Provider, then enter:

• Endpoint URL: the provider’s S3 API endpoint, starting with https://. Enter just the server, without a path (for example https://s3.us-west-004.backblazeb2.com, not a URL with the bucket in it).
• Region: the region requests are signed for. Leave it blank to use the provider’s default.
• Access Key ID and Secret Access Key: an access key that can write to the bucket. Role-based authentication only works with Amazon S3.
• Bucket Name: the name of your bucket.

DocSpring uploads with path-style requests (https://<endpoint>/<bucket>/<key>), which every provider below supports. The endpoint must be reachable from the internet: DocSpring doesn’t upload to private or local network addresses. The action’s result_data includes the endpoint as s3_endpoint, and s3_url is the object’s URL on that endpoint.

Problems with the endpoint, the access key or the bucket fail the upload and count toward the integration’s failure alerts. Timeouts, rate limits and errors at the provider are retried.

Cloudflare R2

• Endpoint URL: https://<ACCOUNT_ID>.r2.cloudflarestorage.com, with your Cloudflare account ID. For a bucket in the EU jurisdiction, use https://<ACCOUNT_ID>.eu.r2.cloudflarestorage.com.
• Region: leave blank (auto).
• Access key: in the Cloudflare dashboard, go to R2 → Manage API tokens and create a token with Object Read & Write permission for your bucket. Use its Access Key ID and Secret Access Key.

Google Cloud Storage

• Endpoint URL: https://storage.googleapis.com
• Region: leave blank (auto).
• Access key: in the Google Cloud console, go to Cloud Storage → Settings → Interoperability and create an HMAC key for a service account with the Storage Object User role on your bucket. (Replacing a file at the same path needs more than Storage Object Creator.) Use its access ID and secret.

Backblaze B2

• Endpoint URL: your bucket’s S3 endpoint, shown on the bucket’s page, such as https://s3.us-west-004.backblazeb2.com.
• Region: leave blank. DocSpring reads it from the endpoint (us-west-004).
• Access key: under Application Keys, add a key with Read and Write access to your bucket. Use its keyID as the Access Key ID and its applicationKey as the Secret Access Key.

Wasabi

• Endpoint URL: the service URL for your bucket’s region, such as https://s3.us-east-1.wasabisys.com or https://s3.eu-central-1.wasabisys.com.
• Region: leave blank. DocSpring reads it from the endpoint.
• Access key: create an access key for a Wasabi user whose policy allows s3:PutObject on your bucket.

DigitalOcean Spaces

• Endpoint URL: your bucket’s region endpoint, such as https://nyc3.digitaloceanspaces.com.
• Region: leave blank (us-east-1 is used for signing).
• Access key: under Spaces Object Storage → Access Keys, create a key with read and write access to your bucket.

MinIO

• Endpoint URL: the HTTPS address of your MinIO server’s S3 API, such as https://minio.example.com. It needs a valid TLS certificate and a public address.
• Region: leave blank unless your server sets one (MINIO_SITE_REGION). The default is us-east-1.
• Access key: create an access key whose policy allows s3:PutObject on your bucket.

Other S3-compatible storage

Choose Other S3-compatible storage, and enter the provider’s S3 endpoint and the region it expects (or leave it blank for us-east-1).

Use Cases

• Compliance - Keep document copies in your own infrastructure
• Backup - Automatic backup of all generated documents
• Integration - Trigger workflows using S3 event notifications
• Analytics - Process documents with your own tools
• Archive - Long-term storage with S3 lifecycle policies

FAQ

How can I configure the S3 integration to only upload certain PDFs?

You can use the “Submission Type”, “Template IDs”, “Folder IDs” and “API Token IDs” fields and the object key templates to configure which PDFs will be uploaded to your S3 bucket.

For example, if you set “Submission Type” to live, then DocSpring will only upload live PDFs to S3 (without watermarks.) Test PDFs will be skipped. The other options are “test”, and “all” (for both test and live PDFs.) The Submission Type setting doesn’t apply to combined PDFs. To stop uploading combined PDFs, leave “Object Key Template for Combined PDFs” blank.

To upload submissions for only some of your templates, list their template IDs in “Template IDs”, or list folder IDs in “Folder IDs” to upload submissions for every template in those folders and their subfolders. When both are set, a submission is uploaded if its template matches either one.

You can also provide a comma-separated list of API tokens in the “API Token IDs” field. If you provide one or more API token IDs, then DocSpring will only upload submissions (or combined submissions) that were created using one of these API tokens. Submissions and combined submissions created without an API token (for example from the dashboard or a web form) are still uploaded. You could use this feature to set up S3 buckets for different environments (e.g. dev, staging, production, qa), and use separate API tokens for each environment. This would allow you to send your generated PDFs into the correct S3 bucket for each environment while sharing the same templates in a single DocSpring account.

Which authentication method should I use?

We recommend using role-based authentication as it’s more secure than sharing access keys. With role-based authentication:

• No long-term credentials are shared between DocSpring and your AWS account
• You can easily revoke access by modifying the trust relationship
• You have more granular control over permissions
• You can use AWS CloudTrail to audit role assumption activities

Does DocSpring still keep a copy of the PDF?

Yes. This AWS S3 integration is just a one-way file upload, but DocSpring continues to store your template PDFs and generated PDFs. We serve our own copy of the generated PDF when you request a download URL. We will also use our own copy of the PDF when merging them into a “combined submission”.

Does DocSpring delete the PDF from my S3 bucket when a submission expires?

No. DocSpring will only delete our own copy of the PDF when a submission expires. We will never delete a PDF in your custom S3 bucket.

How can I tell when the PDF has been uploaded to my custom S3 bucket?

One thing to be aware of is that the submission state will change to processed as soon as our copy of the PDF is ready, but it might take a few seconds before the PDF is uploaded into your custom S3 bucket. The AWS integration upload happens after the initial processing is completed.

If you need to know when the files are available in your own S3 bucket, you can check the actions array in the API response. This array will be empty before the submission is processed. As soon as the submission is processed, it will contain an entry for the aws_s3_upload action. This action’s state will be pending until the file has been uploaded into your S3 bucket, and then it will change to processed. When a Word document is uploaded, the action’s result_data has its docx_s3_key and docx_s3_url as well as s3_key and s3_url, which are the PDF’s (or, when no PDF is uploaded, the Word document’s, or the OpenDocument file’s when it’s the only file), and an OpenDocument file’s are odt_s3_key and odt_s3_url. If a Word template’s PDF, Word document or OpenDocument file is made after the submission is processed (for example with Generate More Files), it’s uploaded when it’s ready, in an action of its own. If an upload fails because of your bucket or the integration’s settings, the state changes to failed and error_message explains why. Uploads that fail because your bucket or role policy denies access are retried automatically, so they go through once you fix the policy. Uploads that fail because of a wrong access key, bucket name, or region are not retried. An error state means the upload failed because of a problem at DocSpring, which we retry.

If uploads keep failing, DocSpring emails you and eventually disables the integration. See When an integration fails.

For example, here’s how you could wait for the PDF to be uploaded to your own S3 bucket (in JavaScript):

const pdfHasBeenUploadedToS3Bucket = () => {
  if (submission["actions"].length === 0) return false;
  const action = submission["actions"].find(
    (a) => a.action_type === "aws_s3_upload",
  );
  return action && action.state === "processed";
};

Another thing you could do is set up an AWS S3 event notification. You could send a webhook to your server as soon as the PDF has been uploaded to your S3 bucket. This means that you wouldn’t need to do any polling.

What if my path template generates a duplicate key?

If a path template generates a duplicate key, any existing files will be overwritten with the new file. To protect against this case, you should enable “Versioning” for your S3 bucket. This means that you will always be able to restore an original file in case it is accidentally overwritten with a duplicate key. Your path template should also use at least one variable that is guaranteed to be unique, such as submission_id.

Danger

Don’t rely on the timestamp variable to provide unique filenames, because multiple PDFs could be processed within the same second.