FileLink API

With the FileLink API, you can automate creating FileLinks from other applications using the API.

Same as with the Filedrop and the standard messages based sending of files, you need to upload the files to the LiquidFiles server first and retrieve the attachment id before calling this File Request API, please see the Attachments API for instructions how to upload the files.

Request

Request URL: /link
Request VERB: POST
  Parameters:
    link:
      attachment                 # Integer. The attachment ID of the uploaded file to create the FileLink for.
      expires_at                 # Date.    The date when the FileLink will expire. Format: YYYY-MM-DD. Defaults
                                 #          to the number of days in the future as configured in the Groups config.
      download_receipt           # Boolean. Default: true. If set to false, the LiquidFiles system will not send
                                 #          download receipts when someone downloads a file using this FileLink.
      require_authentication     # Boolean. If the FileLink requires authentication when downloading or not.
                                 #          The Default value is configured in the Group settings.
Response:
  link:
    url                          # String.  The URL where the receipient can respond to the file request.

The http response codes are 200 OK if the File Request was successful, and 422 Unprocessable Entity if anything went wrong. In case of an error, there's also an error message with what went wrong.

Example Request in XML

<?xml version="1.0" encoding="UTF-8"?>
<link>
  <attachment>12345</attachment>
  <expires_at>2014-01-01</expires_at>
  <download_receipt>true</download_receipt>
  <require_authentication>true</require_authentication>
</link>

Example Response in XML

<?xml version="1.0" encoding="UTF-8"?>
<request>
  <url>http://test.host/requests/v3rQgreL93UHjXmkmFrXP3</url>
</request>

Example Request using curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

# Uploading the actual file and get attachment id for each file
attachment_id=`curl -X POST --user "$api_key:x" -F Filedata=@bigfile.zip $server/attachments`

# Send the message
cat <<EOF | curl -s -X POST --user "$api_key:x" -H 'Content-Type: text/xml' -d @- $server/link
<?xml version="1.0" encoding="UTF-8"?>
<link>
  <attachment>$attachment_id</attachment>
</link>
EOF

Listing FileLinks

You can list the available FileLinks using a GET request to /link like this:

Request URL: /link
Request VERB: GET
  Parameters:
    limit:           # Integer. Optional parameter that will limit the output of number of FileLinks to this value.

Example Request using curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X GET --user "$api_key:x" -H 'Content-Type: text/xml' $server/link?limit=2

Example Response

<?xml version="1.0" encoding="UTF-8" ?>
<links>
 <link>
 <id>zVr9XIeOApNDeca7SnxqE3</id>
 <filename>File1.zip</filename>
 <size type="integer">22310238</size>
 <size_human type="string">21.3 MB</size_human>
 <url type="string">https://liquidfiles.example.com/link/zVr9XIeOApNDeca7SnxqE3</url>
 <expires_at type="date">2013-12-22</expires_at>
 </link>
 <link>
 <id>tzMNVK0sbpXFFlld65s4Ly</id>
 <filename>File3.zip</filename>
 <size type="integer">894661</size>
 <size_human type="string">874 KB</size_human>
 <url type="string">https://liquidfiles.example.com/link/tzMNVK0sbpXFFlld65s4Ly</url>
 <expires_at type="date">2013-12-22</expires_at>
 </link>
</links>

Deleting a FileLink

Request URL: /link/link_id
Request VERB: DELETE

Example Request using curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X DELETE --user "$api_key:x" -H 'Content-Type: text/xml' $server/link/tzMNVK0sbpXFFlld65s4Ly

Response Code

There are three possible response codes as a result of the request:

200: Success - The FileLink was deleted.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.

Updating Parameters

When you have added a FileLink and you want to change some parameters such expiration date, authentication and download notifications.

Updating Require Authentication

Request URL: /link/link_id/update_authentication
Request VERB: PUT
  Parameters:
    require_authentication:     # Boolean. True if users should be required to authenticate to download.

Example Request using curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H 'Content-Type: text/xml' -d '<require_authentication>false</require_authentication>' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_authentication

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted, i.e. the user is not allowed to change if the download should be authenticated or not.

Updating Download Notification

Request URL: /link/link_id/update_download_confirmation
Request VERB: PUT
  Parameters:
    send_download_confirmation:     # Boolean. True if download notificaions should be sent.

Example Request using curl

#!/bin/bash

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H 'Content-Type: text/xml' -d '<send_download_confirmation>false</send_download_confirmation>' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_download_confirmation

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.

Updating Expires At

Request URL: /link/link_id/update_expires_at
Request VERB: PUT
  Parameters:
    expires_at:     # Date. Expiration date in YYYY-MM-DD.

Example Request using curl

#!/bin/sh

# Some nice variables
api_key="Y9fdTmZdv0THButt5ZONIY"
server="https://liquidfiles.example.com"

curl -X PUT --user "$api_key:x" -H 'Content-Type: text/xml' -d '<expires_at>2015-04-18</expires_at>' $server/link/tzMNVK0sbpXFFlld65s4Ly/update_expires_at

Response Code

There are three possible response codes as a result of the request:

200: Success - The request change was carried out successfully.
404: Not Found - The FileLink ID wasn't found.
422: Not Permitted - The Request wasn't permitted.