Uploading files via an API

As well as uploading files via the user interface, it is also possible to do so using an API.

There are a few reasons you may wish to do this. Firstly, API tokens allow people who are not workspace members to upload to the workspace. Secondly, the use of the API allows users to upload data programmatically. For example, perhaps you have a regular stream of data coming into your study and you want it to be automatically pushed on to your workspace.

Generate an upload token

First, go to the Upload dropdown menu and select Manage upload tokens. This will take you to a new tab showing existing tokens and a form to generate new ones.

Upload drop down.png

Provide a reason for the token generation and select the validity period for your new token – the default is set to the maximum (30 days).

If you tick the 'Upload data to database' checkbox, uploaded CSV files and associated metadata will be used to create a database table. Ticking the 'Move files directly to:' checkbox will allow you to upload directly to a specific folder in the workspace. If you do not check either, then files will be uploaded to your workspace Inbox.


Your new token will be listed as the first entry in the table. Use the Copy button to copy your token to your clipboard.


Be aware that once you close the tab you will not be able to copy the token anymore. Save the copied token if you wish to use it again.

Download AzCopy

To use the API, you will need to download AzCopy to your computer. You can add the AzCopy directory to your path, which allows you to use AzCopy from any directory on your system.

If you choose not to add the AzCopy directory to your path, you'll have to first navigate to the location of your AzCopy executable before using it in the command line.


Upload your files

To run AzCopy on your own machine, if you did not add it to your path, first navigate to the location where you have installed AzCopy and run the following command:

azcopy copy "/path/to/your/file" "token"

If you want to recursively copy data (add all files in your folder) from a local directory, add the --recursive=true flag at the end.


Depending on whether you checked the 'Upload data to database' box, the files uploaded through an API will be found either in the Database tab or in the Inbox.

Updated on March 18, 2024

Was this article helpful?