Skip to main content
POST

Overview

The Upload Attachment endpoint allows you to attach a single file to an expense record. This is essential for maintaining proper documentation, compliance with tax regulations, and audit trails. Expenses support one attachment at a time - uploading a new file replaces the previous one.
Security Note: Files undergo multiple validation checks including MIME type verification and content validation to ensure security.
Each expense supports only one attachment. Uploading a new file will replace the existing attachment.

Path Parameters

string
required
The CzUid of the expense to attach the file to

Request Body

This endpoint uses multipart/form-data encoding for file uploads:
file
required
The file to upload. See supported file types below.

Supported File Types

Files are validated at multiple levels:
  1. Extension validation
  2. MIME type verification
  3. Content header validation (e.g., PDFs must start with %PDF)

File Size Limits

Response

object
Information about the uploaded attachment
string
Success message confirming the upload

File Storage and Security

Storage Location

Files are stored securely on the server with:
  • Organized structure: galleries/expenses/{firm_id}/{year}/{month}/
  • Unique filenames: Generated to prevent conflicts and enhance security
  • Access control: Only accessible to authorized users of the owning firm

Security Measures

  • File validation: Content type verification beyond extension checking
  • Virus scanning: Files may be scanned for malware (implementation dependent)
  • Access logging: Download access is logged for audit purposes
  • Firm isolation: Attachments are strictly isolated per firm

Integration with Expense Workflow

Automatic Attachment Detection

When retrieving expenses, attachments are automatically detected:

Document Management

Attachments become part of the expense’s permanent record:
  • Audit trail: Preserved for compliance and audit requirements
  • Version control: Multiple attachments can be added to an expense
  • Integration: Can be referenced in reports and exports

Common Use Cases

Invoice Documentation

Receipt Management

Supporting Documentation

Best Practices

File Organization

  1. Naming conventions: Use descriptive filenames that identify the expense
  2. File types: Prefer PDF for official documents, JPEG/PNG for photos
  3. File sizes: Optimize images to reduce file size while maintaining readability
  4. Descriptions: Always include meaningful descriptions for better organization

Upload Workflow

  1. Validation: Check file type and size before uploading
  2. Progress indicators: Show upload progress for large files
  3. Error handling: Implement proper error handling and user feedback
  4. Backup strategy: Consider keeping local copies of important documents

Security Considerations

  1. File scanning: Scan uploaded files for malware before processing
  2. Access control: Ensure only authorized users can upload attachments
  3. Data privacy: Be mindful of sensitive information in uploaded files
  4. Retention policies: Establish policies for how long attachments are kept

Integration Tips

  1. Bulk uploads: For multiple files, upload them sequentially to avoid overwhelming the server
  2. Mobile optimization: Optimize upload process for mobile devices with potentially slower connections
  3. Automated uploads: Consider automated workflows that upload documents from email or document management systems
  4. Thumbnail generation: For images, consider generating thumbnails for better UI experience

Authorizations

Authorization
string
header
required

Use your API key (sk_live_xxx or sk_test_xxx)

Path Parameters

id
string
required

Expense CzUid

Body

multipart/form-data
file
file
required

PDF or image file (max 10MB)

Response

Attachment uploaded successfully

success
boolean
data
object
meta
object