A guide to using the valdr R package

The valdr package simplifies common interactions with VALD's External APIs. Key features include:

Easy setup

Once you set your API credentials, the package stores them securely ready for use.

Straightforward access to your data

Fetch profiles, test results, and trial data using simple functions built specifically for VALD APIs.

Built-in helper tools

We've built tools to handle authentication, pagination, request formatting, and date filtering for you.

Smart session logic

Automatically tracks your last successful pull and fetches only new data (unless you override it).

Analysis-ready output

Data is returned as easy-to-use R data frames or lists - ideal for use in RStudio, or exporting to other third-party tools such as Power BI or Excel.

You can install the valdr package through the RStudio Tools menu or using the R Console.

Option 1 – Tools GUI (Recommended)

1. Open RStudio on your computer.
2. Navigate to Tools > Install Packages.
3. Ensure 'Install from:' is set to Repository (CRAN).
4. In the Packages field, enter valdr.

5. Click Install.

Option 2 – R Console

1. In the Console, enter the following command and wait for the package to install successfully.

install.packages("valdr")

I'm receiving a dependency error

The valdr package has several required dependencies – if these aren't already on your machine, you will receive an error when trying to install the valdr package.

To view these dependencies, search for valdr in the RStudio Packages pane and open the DESCRIPTION file as shown. Dependencies are listed under Imports.

Once the dependencies are installed, please try installing the valdr package again.

Before you can use any functions from the valdr package, you need to load the package into your R session. This can be done one of two ways.

Load the entire package

This will tell R that you want to use functions from the valdr package in your current session.

In the RStudio Console, enter the following command:

library("valdr")

Call the package for each function

If you don't run the library command first, you will need to write the full path each time you call a function. This includes the package name followed by the :: operator before the function you would like to call.

In the RStudio Console, add the package name before the function like this:

valdr::set_credentials()

Before calling any data functions, you must configure your VALD API credentials through the RStudio Console using the following command:

set_credentials(
  client_id     = "Input your VALD API Client ID",
  client_secret = "Input your VALD API Client Secret",
  tenant_id     = "Input your VALD Tenant ID",
  region        = "Input your VALD region code (e.g., aue, use, euw)"
)

If you didn't use the library("valdr") command earlier, you will need to add valdr:: to the start of this command.

You only need to run this command once, unless you need to update your credentials in future.

Your credentials are securely stored in your system's keyring (Windows Credential Manager | macOS Keychain | Linux Secret Service). Non-sensitive configuration information is saved to a local JSON file in your home directory (~/.vald_config.json).

Your first data fetch will require a start date to define how far back to retrieve test data. This value is then refreshed automatically, so future sessions will continue from where you last left off – only retrieving new data since your most recent fetch.

Set your start date

Enter the following command in your RStudio Console – you can choose a different date.

set_start_date("2025-07-01T00:00:00Z")

Specify a start date for a one-off fetch

After setting a start date, you can manually specify the start date for a one-off fetch by passing it as an argument to any of the data fetching functions shown in the below section. This will not override the saved value.

Your start date must be written in ISO 8601 UTC format (YYYY-MM-DDT00:00:00Z)

To fetch your data you must do the following:

1. Choose a function
2. Assign an object name to the function output

If you don't assign a name to the function output, your data will still be fetched but may not be easily readable in RStudio.

There are limits on the amount of data that can be returned in a single request. See our FAQs > Data Limits section below.

Choose a function

Depending on the system you are fetching data for, you can choose from the below functions.

Profiles

ForceDecks

ForceFrame

NordBord

SmartSpeed

For a list of all available functions, click on valdr in the Packages pane in RStudio. These functions are all hyperlinked with further information on how they can be used.

Assign an object name to the function output

With your chosen function, you will need to create an object and add this to the start of your command in the Console. This allows you to call on the object to visualize the data later.

For this example we will use the get_forcedecks_data() with an object we've called data. Fetch times will vary depending on the amount of data you are retrieving.

data <- get_forcedecks_data()

<- Keyboard Shortcut   (Alt / Option + -)

Optional parameters

You can also pass optional parameters to the function by including them in the parentheses of the function call. The parameters available will differ depending on the function you select, and these can be viewed by clicking on the function in the Packages pane as above.

For example, for most ForceDecks functions you can set the parameter include_attributes which will pull an additional data frame containing various settings e.g., tags and extra test-type-specific fields such as box height in a Drop Jump.

data <- get_forcedecks_data(include_attributes = TRUE)

As mentioned in Step 4 Set your start date, you can override the saved start_date value by passing it directly on any data-fetching functions. This will not overwrite the stored value, it simply applies the date for that call only.

data <- get_forcedecks_data(start_date = "2025-05-01T00:00:00Z)

After you have fetched your data using a function in the Console, you can use built-in functions to visualize the data any way you like.

Here are a few examples of how you can view different data-fetching functions.

get_forcedecks_data()

The get_forcedecks_data() function will return four separate data frames – Profiles, Result Definitions, Tests, and Trials.

In this example we have used the built-in View() function to display the Profiles list in a new tab above the Console.

data <- get_forcedecks_data()
View(data$profiles)

This same logic applies if you wanted to view result definitions, tests, or trials data.

View(data$result_definitions)
  View(data$tests)
  View(data$trials)

get_forcedecks_tests_only()

The get_forcedecks_tests_only() function will fetch test data only. You can simply add the object/variable name to your View() command.

get_forcedecks_trials_only()

The get_forcedecks_trials_only() function will fetch trial data based on the previously retrieved get_forcedecks_tests_only()function above. You must add the test object/variable to your fetch function as shown.

You can easily export specific data frames from RStudio using the write.csv() function. This will save the data to your Downloads folder in CSV file format, which you can then open in Microsoft Excel, Google Sheets, or any spreadsheet tool.

get_forcedecks_data()

In this example we will be exporting the Profiles list we pulled earlier.

macOS

write.csv(data$profiles, "~/Downloads/profiles.csv", row.names = TRUE)

Windows

write.csv(data$profiles, "C:/Users/UserName/Downloads/profiles.csv", row.names = TRUE)

Replace 'UserName' with your actual Windows user name.

Once you have exported data from RStudio, you can easily bring that data into Power BI for further analysis and visualization.

1. Open Power BI Desktop.
2. Navigate to Home > Get data > Text/CSV.
3. Browse to your saved file location and select the file.
4. Click Load to import the data into your Power BI report.

Once loaded, the table will appear in the Fields panel, and you can start building visuals from it just like any other data source.

Power BI automatically recognises headers and data types, but you can review or adjust these in the Transform Data view if needed.

At the start of every R session, you need to load the valdr package into memory by entering this command in the Console.

library("valdr")

Your saved credentials will be loaded automatically, then you can start fetching and viewing data using the steps above as a guide.

Now that you have valdr up and running, consider using the companion R package valdrViz to gather insights from your ForceDecks test data.

Check out our guide to the valdrViz R package to get started.

There are limits on the amount of data that can be returned in a single request. We have implemented the recommended pagination logic documented in our External ForceDecks API documentation to avoid any rate limiting instances for larger queries or misuse.

For further information on how to work with our External APIs, please see our guide on How to integrate with VALD APIs.

When you run any data-fetching function, the package will:

• Look for a cached access token in the keyring.
• Decode the token and check its expiry time based on the exp claim in the JWT payload.
• If the token is still valid, it is silently reused.
• If the token has expired or is missing, a new token is automatically requested using your saved credentials and stored securely for future use.

This ensures secure, automatic authentication with no manual token refresh and optimized performance.

If you restart R, simply run load_credentials() to reload your saved configuration.

The valdr package will be updated periodically on CRAN with improvements, fixes and enhancements. When a new version is released you will be notified in the R Console at the start of a new session.

To install the latest version from CRAN, run:

install.packages("valdr")

You can also use the RStudio GUI by navigating to Tools > Check for Package Updates.

After updating, ensure you run load_credentials() to reload your saved configuration before calling any API functions.

Credentials required

The package does not include any embedded credentials. You must configure your own using set_credentials().

No forced updates

There is no forced update mechanism. You are responsible for checking and applying package updates when available.

No support for custom forks

We do not currently provide support for customized or altered versions of this package.

Token caching

Authentication tokens are cached securely and reused until expiry. Internet access is required to refresh tokens once expired.