This guide explains how to download files using the Files API's pre-signed URL pattern. The download process consists of two steps: getting a pre-signed URL from the API, then downloading directly from S3 storage.

Overview

The file download process is designed for security and efficiency:

API Request: Get file metadata and a pre-signed download URL
Direct Download: Download file directly from S3 using the provided URL
File Access: File is immediately available for use or processing

Step 1: Get Download URL

First, request file metadata and a pre-signed download URL from the API:

Request

curl -X GET https://api.authvia.com/v3/accounts/{account-id}/files/{file-id} \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantId": "AVID0000-0000-0000-0000-000000000000",
  "fileName": "invoice_2024_001.pdf",
  "contentType": "application/pdf",
  "description": "Invoice for customer CUST001",
  "businessProcess": "payment-processing",
  "businessProcessAction": "document-upload",
  "expiresAt": "2024-02-15T10:30:00.000Z",
  "status": "ACTIVE",
  "createdOn": 1705312200000,
  "updatedOn": 1705312200000,
  "downloadUrl": "https://s3.amazonaws.com/bucket/presigned-download-url"
}

Response Fields

Field	Type	Description
`id`	string	Unique file identifier
`merchantId`	string	Account ID that owns the file
`fileName`	string	Original file name
`contentType`	string	MIME type of the file
`description`	string	File description
`businessProcess`	string	Associated business process
`businessProcessAction`	string	Specific action within process
`expiresAt`	string	When the file expires
`status`	string	File status (ACTIVE, EXPIRED, DELETED)
`createdOn`	number	Creation timestamp (epoch)
`updatedOn`	number	Last update timestamp (epoch)
`downloadUrl`	string	Pre-signed URL for downloading

Step 2: Download from S3

Use the pre-signed download URL to download the file directly from S3:

Using cURL

# Download file with original name
curl -O "https://s3.amazonaws.com/bucket/presigned-download-url"

# Download with custom name
curl -o "my_invoice.pdf" "https://s3.amazonaws.com/bucket/presigned-download-url"

File Status

Files have different statuses that affect download availability:

Status Types

Status	Description	Download Available
`ACTIVE`	File is available for use	✅ Yes
`EXPIRED`	File has passed expiration date	✅ Yes (but may be cleaned up)
`DELETED`	File has been removed	❌ No

Error Handling

Common Errors

Error Code	Description	Resolution
`FILE_NOT_FOUND`	File doesn't exist	Check file ID and account permissions
`FILE_EXPIRED`	File has expired	Check file status and expiration
`ACCESS_DENIED`	Insufficient permissions	Verify account access and file ownership
`UNAUTHORIZED`	Invalid or missing authentication	Check your API token
`FORBIDDEN`	Insufficient permissions	Verify account access

S3 Download Errors

Error	Description	Resolution
`Access Denied`	Pre-signed URL expired or invalid	Get a new download URL
`NoSuchKey`	File doesn't exist in S3	Check if file was properly uploaded
`Network Error`	Connection issues	Retry the download