LiquidFiles Documentation
LiquidFiles Documentation
On This Page

Sending files using the Filedrop

Filedrop Info Request

This Filedrop Info Request is unauthenticated, all other requests are authenticated.

In order to make client side validation possible when sending through a Filedrop, you can start by running a Filedrop Info Request like this:

Request Info
Info Value
Request URL /filedrop/_the_filedrop_
Request VERB GET
Authentication No
Response Parameters
Parameter Type Description
api_key String The Filedrop API key, this is used to authenticate uploads and Filedrop submissions. Each time the Filedrop Info Request is called, a unique API is generated. The API key has a lifetime of 1 day so you will need to make sure to complete the Filedrop submission within that timeframe.
If you're submitting multiple Filedrops using this API, you will need to call this info request to get a new API key for each transaction.
name String The name of the Filedrop.
limited_extensions String A comma separated list of accepted file extensions. If configured these are the only permitted file extensions you can send through this Filedrop.
blocked_extensions String A comma separated list of blocked file extensions. If configured these file extensions are not permitted when using this Filedrop. Please note that either limited_extensions or blocked_extensions can be configured, but never both at the same time.
max_upload_size Integer The maximum file size that will be accepted by the Filedrop in Megabytes.

This will respond with details about the Filedrop that can be used to facilitate the Filetransfer (the Filedrop api key) and the file type and file size limitations so that you can implement client side validations of those without having to upload a file.

Example using curl with response

curl -s -H "Accept: application/json" \
     https://liquidfiles.company.com/filedrop/test_filedrop

{"filedrop":
  {
    "api_key":"qiXT9Za7HcXhMTJDBo2oe5",
    "name":"Filedrop Test",
    "limited_extensions":"doc, docx, xls, xlsx, ppt, pptx, png, gif, jpg, jpeg, pdf, zip",
    "blocked_extensions":"",
    "max_upload_size":250
  }
}

If you wanted to just grab the API key, you could run the following:

curl -s -H "Accept: application/json" \
     https://liquidfiles.company.com/filedrop/test_filedrop | \
     ruby -rjson -e 'puts JSON.parse(STDIN.read)["filedrop"]["api_key"]'

Uploading Files

The sending of files is very similar to the sending messages API, with the only change is the URL for the file upload. For detailed instructions how to to upload the file(s), please see the Attachments API.

Request Info
Info Value
Request URL /filedrop/_the_filedrop_/attachments/upload
Request VERB POST
Authentication Required
Headers
Info Value
username the Filedrop API key
password not used (use 'x' if your programming API requires a value)
Content-Type (Optional) LiquidFiles first use the Content-Type HTTP header if that's set. If the Content-Type header is not set it will use this optional parameter. If neither are set, the Content-Type will be detected using the Linux `file` command.
Request Parameters
Parameter Type Description
filename String The filename of the uploaded file.
chunks Integer (optional) When uploading files in chunks (in pieces), these are the total number of pieces there is.
chunk Integer (optional and required when chunks is set) When uploading files in chunks, this is the current chunk number, with the first chunk being chunk number 0 (zero).
Please note that with this binary upload, it's not possible to submit parameters using POST style embedded within the post. Instead, these parameters are submitted using GET style parameters following a question mark (?) on the URL.

Response

As a response to a successful File Upload you will receive an attachment response with the attributes outlined in the Attachment Attributes documentation.

Example Using Curl

There's a couple of things to note in the example, 

#!/bin/bash

# Some variables
filedrop_url=https://liquidfiles.company.com/filedrop/filedrop_test

# retrieve the Filedrop API key
filedrop_api_key=`curl -s -H "Accept: application/json" $filedrop_url | \
  ruby -rjson -e 'puts JSON.parse(STDIN.read)["filedrop"]["api_key"]'`

# Send the file
attachment_id=`curl -s -X POST -H "Accept: application/json" \
  -H "Content-Type: image/jpeg" --data-binary "@imagefile.jpg" \
  --user "$filedrop_api_key:x" \
  $filedrop_url/attachments/upload?filename=imagefile.jpg`
Please note that the Content-Type is set to what the Content Type is of the file that's been uploaded, in this case image/jpeg. Whatever you're sending is going to be trusted. If you set this to application/json, you're going to run into problems. If you don't know the Content Type, don't set any and LiquidFiles will detect the Content Type using the Linux 'file' command.

Creating/Submitting the Filedrop

Request Info
Info Value
Request URL /filedrop/_the_filedrop_
Request VERB POST
Authentication Required
Request Parameters
Parameter Type Description
from String The email address of the sender.
subject String The Filedrop Subject.
message String The Filedrop Message.
attachments Array An array of all uploaded attachment_id's.

Complete example, getting the API key, uploading a file and submitting the Filedrop, using curl

#!/bin/bash

# Variables
filedrop_url=https://liquidfiles.company.com/filedrop/filedrop_test

# retrieve the Filedrop API key
filedrop_api_key=`curl -s -H "Accept: application/json" \
  $filedrop_url | jq .filedrop.api_key`

# Uploading the file
attachment_id=`curl -s -X POST -H "Accept: application/json" \
  --data-binary "@bigfile.zip" --user "$filedrop_api_key:x" \
  $filedrop_url/attachments/upload?filename=bigfile.zip | \
  jq .attachment.id`

cat <<EOF | curl -s -X POST -H "Accept: application/json" \
  -H "Content-Type: application/json" -d @- $filedrop_url
{"message":
  {
    "from":"someone@somewhere.com",
    "subject":"test subject",
    "message":"Please let me know what you think!",
    "attachments":["$attachment_id"]
  }
}
EOF

Response

The Filedop API response is basically a simple OK message that the message has been delivered ok. You can also check for HTTP status code 200. If everything is ok, you should see the following output:

{"message":{"status":"Filedrop message sent successfully"}}

If there's an error, you will see a standard JSON error message like:

{"errors":["You need to attach at least one file"]}