GET
/
external-api
/
v1
/
reports
/
download
/
{id}
Download Report
curl --request GET \
  --url https://getbill.io/external-api/v1/reports/download/{id} \
  --header 'Authorization: <authorization>'
{
  "error": false,
  "message": "Report download information retrieved",
  "data": {
    "id": "report_abc123",
    "filename": "financial_summary_2024_01.pdf",
    "file_size": 245760,
    "mime_type": "application/pdf",
    "download_url": "https://secure-downloads.getbill.io/reports/abc123def456?expires=1706789400&signature=sha256hash",
    "expires_at": "2024-02-01T12:30:00Z"
  }
}

​
Overview

This endpoint provides secure download information for a completed report. Instead of directly returning the file, it provides a time-limited download URL for security purposes.

​
Authentication

Requires a valid OAuth 2.0 access token with the reports:read scope.

​
Request

​
Authorization
string
required
Bearer token for authentication
​
id
string
required
The encrypted ID of the report to download

​
Example Request

curl -X GET "/external-api/v1/reports/download/report_abc123" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Response

​
error
boolean
Always false for successful requests
​
message
string
Success message
​
data
object
Download information and metadata

​
Success Response

{
  "error": false,
  "message": "Report download information retrieved",
  "data": {
    "id": "report_abc123",
    "filename": "financial_summary_2024_01.pdf",
    "file_size": 245760,
    "mime_type": "application/pdf",
    "download_url": "https://secure-downloads.getbill.io/reports/abc123def456?expires=1706789400&signature=sha256hash",
    "expires_at": "2024-02-01T12:30:00Z"
  }
}

​
Security Features

Time-Limited URLs

Download URLs expire after 1 hour for security

Signed URLs

URLs include cryptographic signatures to prevent tampering

Single Use

URLs may be limited to single use depending on report sensitivity

Access Logging

All download attempts are logged for audit purposes

​
Download Process

  1. Get Download Info: Call this endpoint to get the secure download URL
  2. Download File: Use the returned URL to fetch the actual file
  3. Handle Expiry: If the URL expires, call this endpoint again for a fresh URL

​
Complete Download Example

async function downloadReport(reportId, accessToken) {
  try {
    // Get download information
    const infoResponse = await fetch(
      `/external-api/v1/reports/download/${reportId}`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`
        }
      }
    );

    if (!infoResponse.ok) {
      throw new Error('Failed to get download information');
    }

    const downloadInfo = await infoResponse.json();
    
    // Download the actual file
    const fileResponse = await fetch(downloadInfo.data.download_url);
    
    if (!fileResponse.ok) {
      throw new Error('Failed to download file');
    }

    // Create blob and download
    const blob = await fileResponse.blob();
    const url = window.URL.createObjectURL(blob);
    
    const a = document.createElement('a');
    a.href = url;
    a.download = downloadInfo.data.filename;
    document.body.appendChild(a);
    a.click();
    
    // Cleanup
    window.URL.revokeObjectURL(url);
    document.body.removeChild(a);
    
  } catch (error) {
    console.error('Download failed:', error);
  }
}

​
Error Responses

{
  "error": true,
  "message": "Access denied to this report",
  "code": 403
}

​
Best Practices

Check Status First

Verify the report status is “completed” before attempting download

Handle Expiry

Implement retry logic for expired download URLs

Validate File Size

Check the expected file size matches what you receive

Secure Storage

Store downloaded reports securely if caching locally