File Uploads

DayZero uses S3-backed file storage for bill attachments, transaction receipts, CSV imports, and other documents. Two upload methods are available.

Presigned Upload (Recommended)

Get a presigned upload URL, then upload the file directly to S3 from the client:

Step 1: Request a presigned URL

bash
curl -X POST "https://api.ondayzero.com/api/v1/upload" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -H "Content-Type: application/json" \
  -d '{"filename": "receipt.pdf"}'

Returns an upload_url (presigned S3 PUT URL) and an s3_key to reference the file.

Step 2: Upload to S3

bash
curl -X PUT "{upload_url}" \
  -H "Content-Type: application/pdf" \
  --data-binary @receipt.pdf

Step 3: Use the s3_key

Pass the s3_key when creating or updating entities (e.g., s3_key on a bill, transaction attachment, etc.).

Direct Upload

Upload a file directly through the API (simpler but slower for large files):

bash
curl -X POST "https://api.ondayzero.com/api/v1/upload/direct" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -F "file=@receipt.pdf"

Returns the s3_key for the uploaded file.

Download a File

Get a presigned download URL:

bash
curl "https://api.ondayzero.com/api/v1/upload/download?s3_key=path/to/file.pdf" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Or stream the file directly:

bash
curl "https://api.ondayzero.com/api/v1/upload/stream?s3_key=path/to/file.pdf" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID" \
  -o downloaded-file.pdf

List Uploaded Files

bash
curl "https://api.ondayzero.com/api/v1/upload/files" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Optionally filter by source to see files from a specific upload context.

CSV Templates

Download CSV templates for bulk imports:

bash
curl "https://api.ondayzero.com/api/v1/upload/templates" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"

Get a specific template:

bash
curl "https://api.ondayzero.com/api/v1/upload/templates/{template_name}" \
  -H "Authorization: Bearer dz_your_token_here" \
  -H "x-business-id: YOUR_BUSINESS_ID"