Best Practices for Integrating with Files.com

The Files.com platform provides built-in capabilities to connect to external systems, including built-in connectors to external storage solutions, identity solutions, and notification services. The platform also provides built-in workflow tasks, such as Automations, Syncs, and Folder Settings, that can be used to automate encryption and data movement between systems. We also provide multiple ways for you to integrate with us.

We provide SDKs, RESTful APIs, a Command Line Integration (CLI) App, and an MCP Server. Each offers a different path so you can pick what fits your environment.

Customers also integrate with Files.com through iPaaS platforms, including Microsoft Power Automate, Azure Logic Apps, Boomi, Zapier, and MuleSoft, using official connectors from those platforms.

Most integrations either move files between systems or interact with the Files.com platform to manage configuration and operational data. Identifying which category applies determines the right integration method.

Identify the Type of Integration

Before selecting an integration method, decide which category fits the work.

Integrations That Move Files

Many integrations exist primarily to move files between Files.com and other systems.

Examples include:

• Uploading or downloading files from an application
• Automating partner file exchanges
• Collecting files through an Inbox or inbound Share Link
• Distributing files through Share Links
• Moving files between storage systems

Some integrations only transfer files. Other integrations must also control what happens to files after they arrive on Files.com. For example, an application may upload a file and then rename it, move it to another folder, create a Share Link, or trigger additional processing.

Several integration methods support these scenarios depending on the environment where the integration runs.

Use a Files.com SDK for applications written in a programming language that Files.com supports. The SDK provides a developer-friendly interface that simplifies authentication, request formatting, error handling, and retries. When using an iPaaS platform, use our corresponding iPaaS connector.

Use the Files.com CLI app for Script-based automation environments. Command-line environments that use shell scripts, PowerShell scripts, and CI/CD pipelines can invoke the CLI app directly without requiring custom API client implementations.

Integrate using the REST API for applications written in languages where a Files.com SDK isn't available. API integrations work from any environment but require the application to handle authentication, request formatting, retries, and error handling.

Some systems cannot run custom application code or API integrations. Legacy systems, partner platforms, and third-party tools often rely on traditional file-transfer interfaces. For these environments, integrate using SFTP, FTPS, FTP, or, as a last resort, WebDAV.

Integrations That Interact With the Files.com Platform

Other integrations interact with Files.com as a platform rather than using it only as a file transfer endpoint.

Examples include:

• Provisioning or managing users
• Managing folder permissions
• Retrieving logs or audit records
• Automating administrative tasks
• Managing site configuration
• Performing operational reporting

These integrations require direct interaction with the Files.com platform rather than simple file transfer interfaces.

Use a Files.com SDK for applications written in supported programming languages because it exposes the full capabilities of the platform through a developer-friendly interface. When using an iPaaS platform, use our corresponding iPaaS connector.

Use the Files.com CLI app for operational automation environments that implement administrative scripts or CI/CD pipelines. The CLI app allows scripts to perform repeatable administrative tasks without requiring custom API client code.

Use Terraform for infrastructure and configuration automation workflows. Terraform allows administrators to define Files.com configuration as code and manage that configuration using infrastructure-as-code practices.

Interact with Files.com through the REST API when using applications written in languages where an SDK is not available.

File transfer protocols (FTPS, SFTP or WebDAV) are not appropriate for administrative integrations because those protocols only provide file access and do not expose platform management capabilities.

Integrations with AI Agents and LLM Tools

If you're giving an AI agent or LLM-based tool access to your Files.com site, determine whether you can use the Files.com MCP Server rather than building your own SDK or API integration from scratch. The most frequently used features are available as MCP tools for you to use. This helps you set up safe access to allow an AI assistant to upload files, list folders, manage users, and more.

The Files.com MCP Server exposes Files.com capabilities as structured tools that AI models can call directly. This is a better fit than wrapping SDK calls in custom code because the MCP Server handles the connection between your AI system and your Files.com site.

Integration Method Decision Guide

Start by identifying what your integration needs to accomplish.

Move Files

Use these approaches when your integration transfers files between Files.com and other systems.

• Application written in a supported programming language: Use a Files.com SDK.
• Shell scripts, PowerShell scripts, CI/CD pipelines, or automation scripts: Use the Files.com CLI app.
• Application written in a language without a Files.com SDK: Use the REST API.
• External system only supports file-transfer interfaces: Use SFTP, FTPS, or WebDAV.

Interact With the Files.com Platform

Use these approaches when your integration manages the Files.com platform itself.

Examples include user provisioning, retrieving logs, managing permissions, and automating administrative tasks.

• Application written in a supported programming language: Use the Files.com SDK.
• Operational automation or scripting environments: Use a Files.com CLI app.
• Infrastructure or configuration automation: Use Terraform.
• Application written in a language without a Files.com SDK: Use the REST API.

Additional Method Details

Each integration method has its own strengths and target environments.

SDKs

We provide SDKs for 7 programming languages: Go, Java, JavaScript, Microsoft .NET, PHP, Python, and Ruby.

When your application is written in a supported language, the SDK is the recommended choice. Our SDKs use our secure APIs and include developer-friendly features such as built-in automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking where available. They provide the tightest integration between our APIs and your programming language of choice.

Some SDKs include further optimizations for file operations, such as parallelization of uploads and downloads.

As we add new platform features, our SDKs are automatically updated to support them.

iPaaS Connectors

We provide iPaaS connectors for Microsoft Power Automate, Azure Logic Apps, Boomi, Mulesoft, and Zapier.

These official connectors are recommended when your business processes already run on one of these iPaaS platforms, or when your organization prefers no-code or low-code integration approaches that let business and technical teams automate workflows without writing custom code.

The Boomi, Mulesoft, and Zapier connectors use our SDKs and inherit their built-in features including automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking where available.

The Power Automate and Logic Apps connector uses our official secure APIs to optimize file transfers between Files.com and your business workflows.

CLI

The Command Line Integration (CLI) App is cross-platform and available for Windows, Linux, and Mac.

The CLI App is the recommended choice for integration from a scripting language such as PowerShell, shell scripts (bash, csh, zsh, etc.), and DOS batch files (BAT). It uses our secure APIs and provides built-in automatic retries, fast performance, automatic pagination handling, and automatic transfer chunking.

You can specify the output format (JSON, CSV, or table) for easier post-processing within your script.

As we add new platform features, the CLI App is automatically updated to support them.

Terraform

Terraform provides Infrastructure-as-Code (IaC) management for Files.com administrative resources, with versioned configuration, repeatable deployments, and safer automation across environments.

Terraform users define configuration using a declarative configuration language known as Terraform Configuration Language, or optionally JSON.

The Files.com Provider for Terraform allows you to automate the management of your Files.com site, including resources representing users, groups, folders, share links, inboxes, automations, security, encryption, access protocols, permissions, remote servers, remote syncs, data governance, and more.

Use Terraform if you have implemented infrastructure-as-code practices at your organization.

APIs

We provide RESTful web service APIs. Any HTTP client can call them, including those built into programming languages, scripts, and iPaaS platforms.

The APIs are the recommended choice for systems that cannot use our SDKs or CLI App.

The raw APIs give you direct access to platform microservices, but you'll need to build your own logic around them to handle response outcomes, retries, and exception handling.

As we add new platform features, the APIs are automatically updated to support those features.

Protocols

We support the file transfer protocols FTP(S), SFTP, and WebDAV for uploading, downloading, moving, copying, renaming, and deleting files and folders. These actions can run from protocol-native batch commands or from external scripts.

Protocols are the recommended choice for transferring files from a system that cannot use our SDKs, CLI App, or APIs, such as embedded systems with built-in file transfer protocol support. They are the least recommended choice for programmatic move, copy, and rename operations.

These protocols were designed before cloud-based platforms and assume all operations execute synchronously. They are unaware of asynchronous background operations and cannot accurately report the current state of a file or folder with an asynchronous operation in progress.

Asynchronous Background Operations

The Files.com platform performs some operations asynchronously, running them in the background in parallel.

When you integrate programmatically from a script or iPaaS process, account for these background operations. A requested change may not be immediately visible or complete when control returns to your code.

For example, moving a file from one Files.com storage region to another, or from one Remote Server Mount to another, creates a background process to move the file. Control returns immediately even though the move is still in progress.

Our SDKs, CLI App, and APIs return responses that indicate when an asynchronous operation has started, along with methods to query its current status and final outcome.

Integration through a protocol gives no indication of whether an operation is asynchronous. Add checks in your script or process to verify that an operation has completed before any further processing steps.

Retries

Our SDKs and CLI App include built-in retry logic that automatically repeats a request when a temporary network interruption or server-side condition prevents it from completing. Integrations recover from transient failures without requiring additional error-handling code. Some protocol clients provide built-in retries for uploads and downloads, but typically for interactive user sessions rather than programmatic scripts.

Our SDKs, CLI App, and APIs return responses that indicate when an action fails, which your programs, scripts, and processes can use to trigger your own retry logic.

Protocol clients may or may not provide exit codes that indicate the outcome of batch commands.

Too many retries, performed too quickly, will look like a cyberattack to network security devices. Use retry logic that increases the duration between attempts.

Parallelism

As a Software-as-a-Service (SaaS) cloud-based platform, Files.com provides elastic scalability that allows for a practically unlimited number of parallel connections.

When using parallel threads or processes, account for the fact that operations may be asynchronous and that other processes or users may be interacting with the same files and folders at the same time.

Performance Considerations

Operations

Operations on the Files.com platform take the same amount of time regardless of how they are triggered.

For example, moving a file from one folder to another takes the same amount of time whether the move was started via SDK, API, CLI App, Automation, Folder Setting, FTP, SFTP, WebDAV, or web portal.

There are caveats. Some protocol clients "copy" a file by downloading it from its source folder and re-uploading it to its destination folder. In that case, the operation takes longer because of the round trip from server to client and back.

Moves and copies from one Files.com storage region to another, or from one Remote Server Mount to another, always take longer than an identical operation whose source and destination reside within the same storage region or location.

Uploads and Downloads

For uploads and downloads, the fastest transfer method is HTTPS via our SDKs, CLI App, APIs, and web portal.

Our SDKs, CLI App, and web portal automatically apply parallelism and chunking to transfers for the best possible performance. When using our APIs directly, your application, program, or script must manage parallelism and chunking on its own.

Protocol-based transfers are slower because of the underlying protocol itself. Transmission speed depends on the encryption methods and how "chatty" the protocol is — meaning how much back-and-forth acknowledgement the client and server exchange. WebDAV runs over HTTPS but is very chatty and very affected by network latency.

On-premises SFTP has traditionally been slower than FTP(S) because of its encryption methods and its use of a single data transmission port. Cloud-based SFTP, however, benefits from SaaS elasticity and is often faster than FTP(S).

WebDAV is convenient for desktop users because it's built into nearly every Windows, Mac, and Linux desktop, but it only performs well over a local area network (LAN). Over the internet, WebDAV is slow because of its network chattiness.

When multiple file transfer options are available, we recommend the following order for transfer speeds, from fastest to slowest:

1. SDKs, CLI App, APIs, or web portal
2. SFTP or FTP(S)
3. WebDAV

Calculating Folder Size

The SDKs and API provided by Files.com don't provide a method to recursively calculate the size of a folder tree. This is because any folder within your site could contain Remote Server Mounts. Some Remote Server types can't provide the size of a folder tree performantly, or even at all.

Anything you build with our SDKs will work the same, regardless of where your files happen to be stored. To fulfill that promise, we do not provide a recursive size function.

Assistance

Our Customer Support team can help you choose and implement the right integration approach for your business processes. Contact us with any questions.