File Attachments

Certain API endpoints allow you to upload files to configure certain objects on the API. Examples of this include uploading avatars to a user record or custom background image for your login screen.

The process used to upload these sorts of files to the API is separate from the main process of uploading files to your Files.com site as part of an actual business file transfer.

Any time an API endpoint accepts a parameter with type File, there are two different ways to upload that file.

One way is to upload it as an HTTP POST parameter using the HTTP multipart/form-data standard. This is the same way that a file that gets uploaded by web browsers when you create a <form method="post" enctype="multipart/form-data"> form in HTML that contains an <input type="file" /> field. The upside of this approach is that it uses a completely standard HTTP technique for uploading files. The downside to this approach is that it breaks from the pattern used everywhere else in our API where JSON bodies are preferred for POST/PUT requests.

As a result of that, the preferred way to upload a file to our API uses a non-standard technique of encoding the file as Base64 and including that Base64 representation in the standard JSON body of the POST/PUT request. When using this approach, you will provide a JSON object with 3 elements:

• filename - the file name of the file
• type - the MIME type of the file
• encoded_data - the actual data of the file encoded using Base64

Please see the cURL example code on the right for an example of the exact format.

When using our SDKs and integrations, please be aware that (unfortunately) support for File Attachments to API requests is somewhat inconsistent. We are very interested in adding support to any SDKs where a customer needs this capability, so please reach out to us and we'll be happy to help.