This covers API version 2, which was implemented in Filetransfer appliance version 1.6
Please see api_v1 for API version 1, for Filetransfer appliance version 1.5 and earlier.
The major change between API v1 and v2 is that authentication in v1 sent the API key in the XML queries and in v2 the API key is sent as http auth. The API key in v2 is persistent so it's possible to save the API key in clients to keep the user logged in. Finally, the API has been extended to allow downloads of files as well.
The Filetransfer appliance has an XML API to facilitate automated filetransfers.
Request URL's
To send these requests, please use a http POST (as opposed to a http GET) request to the following URL's.
| Function | Type | Relative URL | Example URL | Content-Type |
|---|---|---|---|---|
| Login | POST | /login | https://filetransfer.example.com/login | text/xml |
| Account | GET | /account | https://filetransfer.example.com/account | text/xml |
| Upload | POST | /attachments | https://filetransfer.example.com/attachments | part/multipart |
| Message | GET | /message | https://filetransfer.example.com/message | text/xml |
Authentication
The API uses an API key to authenticate users. The API key can be found in the users account page, or by sending an XML authentication request to /login (please see Login API for instructions). An example API request using curl:
curl -H 'Content-Type: text/xml' --user Y1dftMxdZ0THButt5ZONIY:x https://filetransfer.example.com/message
In this example, Y1dftMxdZ0THButt5ZONIY is the API key. Curl, and a lot of other frameworks, require some password to be entered. Please enter 'x' or anything to satisfy the password requirement. The Filetransfer appliance will only look at the username part when authenticating the user.
Please note that the API key is persistent. So if you want keep the user logged in, from the client. Please save the the API key, not the username and password. You don't need to send the username and password if you know the API key.
Response status codes
In the header of the response, there will be a couple of possible status codes. In case of a 4XX error, please see the response body for an error description.
| Status Code | Description |
|---|---|
| 200 | Everything went fine (user found, file uploaded ok, message sent successfully) |
| 401 | Unauthorized, API key or User authentication failed |
| 422 | Something went wrong and the request could not be completed (Email and/or password incorrect, invalid file, invalid message) |
Content-Type and file extension
The Filetransfer appliance API expects requests in XML format (except where otherwise listed). The preferred way to ensuring that the requests are interpreted properly is to set the Content-Type header to 'text/xml' or 'application/xml'. As a fallback, it is also possible to append .xml to requests.
Using curl, examples would look like:
curl -H 'Content-Type: text/xml' --user Y1dftMxdZ0THButt5ZONIY:x https://filetransfer.example.com/account curl -H 'Content-Type: application/xml' --user Y1dftMxdZ0THButt5ZONIY:x https://filetransfer.example.com/account curl --user Y1dftMxdZ0THButt5ZONIY:x https://filetransfer.example.com/account.xml
The first two requests sets the Content-Type, which is the preferred option. The last appends '.xml' to the request.