# Upload Files to User's Storage Area

Use the POST /files transaction to upload a file, multiple files, or a zipped archive to the user's storage area.

## Uses

There are a number of uses of the upload transaction.

### Upload one file to the root

To upload one file to the root of the user's upload area, use the API's endpoint URL without any additional paths, i.e. https://api.ensims.com/users/api/files. Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' https://api.ensims.com/users/api/files

The -F option adds the required “multipart/form-data” encoding type to the request, whereas the file=@/paht/to/file specify which file to upload. Please note the field name must be file for the service to accept the upload.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
"ok" : true,
"fileHandle" : "",
"callback" : "/users/api/files/"
}


### Upload one file to a specific folder

To upload one file to a specific folder in the user's upload area, use the API's endpoint URL with the full path to the target folder, e.g. https://api.ensims.com/users/api/files/test/today. This will upload the file to the folder named /test/today/ in the user's upload area. If the folder does not exist, it will be created.

Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' https://api.ensims.com/users/api/files/test/today

The -F option adds the required “multipart/form-data” encoding type to the request, whereas the file=@/paht/to/file specify which file to upload. Please note the field name must be file for the service to accept the upload.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
"ok" : true,
"fileHandle" : "test/today",
"callback" : "/users/api/files/test/today"
}


### Upload multiple files to a specific folder

To upload multiple files to a specific folder in the user's upload area, use the API's endpoint URL with the full path to the target folder, e.g. https://api.ensims.com/users/api/files/test/today. This will upload the files to the folder named /test/today/ in the user's upload area. If the folder does not exist, it will be created. All files to be uploaded have the same field name file.

Here is the example using cURL:

curl -b .cookies/cookies -F 'file=@test123.txt' -F 'file=@test456.txt' -F 'file=@test789.txt' https://api.ensims.com/users/api/files/test/today

The multiple -F options with the file=@/paht/to/file1 do the trick. Please note if any files already exist in the target folder, it will be overwritten.

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
"ok" : true,
"fileHandle" : "test/today",
"callback" : "/users/api/files/test/today"
}


### Upload a zip archive including the folder structure

Pack the files in a zipped archive may make uploading easier and quicker. Also, you can include the folder structure of the files to upload. Once received, the ENSIMS Web service will unpack the files, including any folder structure, to the target folder in the user's upload area, and return the base folder of the uploaded files.

curl -b .cookies/cookies -F 'file=@tests.zip' https://api.ensims.com/users/api/files/test/zipped

If successful, a successful transaction response as below will be returned. Details of the fields in the confirmation object are explained here.

{
"ok" : true,
"fileHandle" : "test/zipped",
"callback" : "/users/api/files/test/zipped"
}


## Transaction return object

A successful transaction return object contains the status flag and a message as well as the location of where the uploaded files are stored, such as the example below.

{
"ok" : true,
"fileHandle" : "test/today",
"callback" : "/users/api/files/test/today"
}


The fileHandle and the callback fields both point to the location (folder in the upload area) where the uploaded files are stored. They can be used for subsequent access to the uploaded files. If a zip archive is uploaded, its contents will be expanded on the server and the filehandle points to the base folder of the archive.

## Transaction failed response

An HTTP 401 - Unauthorized response will be received if the existing token is invalid.

An HTTP 500 - Server error response will be received if the request is malformed or cannot be processed for some reasons.

## Example using Python Requests

Make sure Requests is correctly installed in your Python environment, and the session token has been stored in the cookies variable after successfully logging on to the service. Run the following lines for uploading various files to different locations in the user's upload area.

import requests

# Upload one file to root
files = {'file': open('test123.txt', 'rb')}

# Upload one file to a target folder
files = {'file': open('test123.txt', 'rb')}

# Upload multiple files to a target folder, including different file types and customizable target file names
files = [
('file', ('5ZoneAirCooled-v93.idf', open('job_example\\5ZoneAirCooled-v93.idf', 'rb'), 'text/plain')),
('file', ('in.epw', open('job_example\\in.epw', 'rb'), 'text/plain'))
]

# Upload files in a zip archive to a target folder
files = {'file': open('job_example\\Shoebox_v8.9.zip', 'rb')}