REST API

Labvanced offers a REST API for users to fetch experiment and session data from their online psychology research.

The REST API is authenticated with a token, that allows you to download all of your data programmatically. The REST API is great for organizations and academic research institutions who want to centralize their data fetching and store their data in dedicated places as per their pipeline protocol. Instead of selecting and downloading data manually and saving it locally, this allows organizations to access the data on their servers which is also important for GDPR protocol.

The documentation (Swagger UI) of the rest endpoints can be found here: https://www.labvanced.com/openapi.html

We also provide an openapi specification that can be used to autogenerate client code for different programming languages (i.e. in tools like Postman): https://www.labvanced.com/labvanced-openapi.json

Creating the API Token

This is a secured API, meaning you need to validate access using a token generated in Labvanced in order to access the data.

To create the token, log into the Labvanced app and go to the ‘My Account’ tab located on the left side of the menu.

There is a section called ‘API Credentials’ and to create the token, simply click ‘Generate.’

When the token appears, double click the token key in order to highlight it all and then Ctrl+C to copy it.

With this token, you will be able to access the data from your studies and the relevant sessions.

Note: the token can only be generated to give access to the session data by the study owner.

Try it out using our API Documentation (Swagger UI)

The simplest way to try out our API is to use the "Try it out" functionality in our API documentation (Swagger UI): https://www.labvanced.com/openapi.html

In the upper right corner, you click ‘Authorize’.

This will open a dialogue box which prompts you to enter / paste the token in the ‘Value’ field.

Once you paste the token, click ‘Authorize’ then ‘Close’ to close the dialog box.

Note: When you are finished looking at the data, you can log out of this session by clicking ‘Authorize’ found at the top right corner of the website and then, in the dialog box that appears, by clicking the ‘Logout’ button that appears in the bottom left corner.

Try out Accessing Data via our API Documentation

Once you are logged in, you can make use of these two areas in order to access your experimental data:

• /api/{expId}/download/{recSessionId}: this section allows you to access and download a single participant’s data. When the data is downloaded it will be in a .csv file format as per the configuration you have specified in the exportSettings found on the ‘Dataview & Export’ page in the Labvanced app.
• /api/{expId}/sessions: allows you to retrieve all the sessions for a specific experiment by inputting the ‘experiment id.’

Data from ‘/api/{expId}/sessions’

It is best to start with the second endpoint to first find out what recording sessions (and their corresponding rec_session_id) exist in a given experiment. You click the second blue field labeled /api/{expId}/sessions and it will open into a larger view and click the ‘Try it out’ button on the right side:

By clicking ‘Try it out’ you will be able to input numbers into the ‘expid’ field to indicate the experiment id you want to access the session data for. You can find this in labvanced in the "My Studies" page in column "ID". Once you fill in this field, you click ‘Execute.’

Once you do this, you can scroll down and see the information for all the sessions in that specific experiment:

Please note down one of the rec_session_id from the response payload to use it in the next section to download all the recorded data of that recording session.

Note: To input a different ‘experiment id’, simply click the red ‘Cancel’ button on the right side, in order to be able to input a new ‘experiment id.’

Data from ‘recSessionId’

To access and download a participant’s data, you click the first blue field labeled /api/{expId}/download/{recSessionId} and it will open into a larger view and click the ‘Try it out’ button on the right side:

By clicking ‘Try it out’ you will be able to input numbers into the two fields that appear by indicating the ‘experiment id’ and ‘rec_session_id’ that you want to download (see previous section).

Once you input these values, simply click ‘Execute’ and the API will run. Then you scroll down, and you will see an option to ‘Download file.’

Upon clicking ‘Download file’ a .zip will be downloaded containing two .csv files, namely the:

• sessions.csv
• trials.csv

These files will contain all the relevant data for the specific session and the associated trial data.

Note: To fetch a different session, simply click the red ‘Cancel’ button on the right side, in order to be able to input a new ‘experiment id’ and a new ‘rec_session_id’ to download.

In conclusion, these steps allow you to access data using the API token you have generated using a unique and secured token in Labvanced in order to view experimental and session data.

Try it out using Postman

This is a second option to try out the API for those who are using Postman (an API platform) already in their day-to-day activities. The Labvanced API token also works from there.

You enter the URL at the top field, based on the Labvanced API website.

Then, select the Key and paste the token under the ‘value’ column, as shown below:

This way, the session data for an experiment will be accessible through Postman.

Similarly, you can follow the same process in order to download files for a specific participant.

When doing this, the preview will show odd characters but this is normal because this command is for fetching files. When you click ‘Save Responses’ and ‘Save to a file’ the data for the particular participant will appear normally.