SFTP Files

The /files folder is a virtual directory that provides SFTP access to the Files API (/v3/accounts/{account-id}/files). This bidirectional connection allows you to upload files via SFTP and access them via API, or upload files via API and access them via SFTP.

Virtual Directory Overview

The /files directory serves as an SFTP interface to your account's file storage:

Files uploaded via SFTP can be listed and accessed via the Files API
Files uploaded via API can be listed and accessed via SFTP
Unified file management across both interfaces

File Operations

Uploading Files

Upload files directly to the /files directory via SFTP:

# Upload a single file
sftp> put local_file.pdf /files/

# Upload to subdirectory
sftp> put document.pdf /files/documents/

Listing Files

List files in the virtual directory:

# List all files
sftp> ls /files/

# List files in subdirectory
sftp> ls /files/documents/

Downloading Files

Download files from the virtual directory:

# Download a file
sftp> get /files/document.pdf

# Download from subdirectory
sftp> get /files/documents/report.pdf

API Integration

Files API Endpoint

The virtual directory connects to the Files API endpoint:

GET /v3/accounts/{account-id}/files
POST /v3/accounts/{account-id}/files
GET /v3/accounts/{account-id}/files/{file-id}
DELETE /v3/accounts/{account-id}/files/{file-id}

Bidirectional Access

Operation	SFTP Method	API Method	Description
Upload	`put` command	`POST /files`	Upload file via either interface
List	`ls` command	`GET /files`	List all files in account
Download	`get` command	`GET /files/{id}`	Download specific file
Delete	`rm` command	`DELETE /files/{id}`	Remove file from storage

File Organization

Directory Structure

Organize files using subdirectories within /files:

/files/
├── documents/
│   ├── invoices/
│   └── contracts/
├── images/
│   ├── logos/
│   └── receipts/
└── data/
    ├── exports/
    └── imports/

File Naming

Use descriptive, consistent file names
Avoid special characters that may cause issues
Include date stamps for versioning when appropriate
Follow your organization's naming conventions

File Metadata

Files can include metadata for organization and search:

Common Metadata Fields

Field	Description	Example
`category`	File category	`invoice`, `receipt`, `document`
`customer_ref`	Associated customer	`CUST001`
`business_process_id`	Associated business process	`bp_123456789`
`tags`	Search tags	`important`, `archived`

Error Handling

Common Errors

Error	Description	Resolution
`FILE_TOO_LARGE`	File exceeds size limit	Reduce file size or contact support
`UNSUPPORTED_TYPE`	File type not supported	Use supported file format
`INSUFFICIENT_SPACE`	Account storage limit reached	Remove old files or upgrade plan
`INVALID_FILENAME`	Filename contains invalid characters	Use valid filename characters
`ACCESS_DENIED`	Insufficient permissions	Check account permissions

Best Practices

File Management

Organize with subdirectories: Use folders to categorize files
Consistent naming: Follow a consistent naming convention
Regular cleanup: Remove files that are no longer needed
Backup important files: Keep local copies of critical files

Security

Validate file types: Only upload supported file types
Check file size: Ensure files are within size limits
Use secure transfer: Always use SFTP for file operations
Monitor access: Review file access logs regularly