File Download Guide

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:

1. API Request: Get file metadata and a pre-signed download URL
2. Direct Download: Download file directly from S3 using the provided URL
3. 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

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

Error Handling

Common Errors

S3 Download Errors