Interface to 'REDCap'

Access data stored in 'REDCap' databases using the Application Programming Interface (API). 'REDCap' (Research Electronic Data CAPture; <>) is a web application for building and managing online surveys and databases developed at Vanderbilt University. The API allows users to access data and project meta data (such as the data dictionary) from the web programmatically. The 'redcapAPI' package facilitates the process of accessing data with options to prepare an analysis-ready data set consistent with the definitions in a database's data dictionary.

Build Status Coverage Status DOI

The package redcapAPI is an R interface to REDCap (, and is an actively developed fork of redcap, originally created by Jeffrey Horner.

Please read the documentation on your institutions REDCap installation.

Issues may be reported at

Please consider contributing tips and clarifications to the package wiki at

This package was developed under REDCap Version 5.8.2. My institution is usually a little behind on updating REDCap and so some features of the API may not always be available.

The redcapDbConnection methods are underdeveloped as I don't personally have access to the REDCap database (and so am unable to test features). If you have that kind of access, feel free to develop the redcapDbConnection methods.


Changes in Version 2.2 (no scheduled date)

  • BREAKING CHANGE: The dev_allocate and prod_allocate elements of the object returned by allocationTable have been named dev_allocation and prod_allocation, respectively.
  • Bug fix: importRecords now handles data with repeating forms correctly.
  • New feature: UTF-8 Characters may be stripped from the data dictionary.

Change up to Version 2.1 (2018-03-03)

  • Bug fix: Add [form]_complete fields
  • Bug fix: Include [form]_complete fields in Reports
  • New feature: [form]_complete fields may be explicitly requested.
  • New feature: Automatic selection of [form]_complete fields may be turned off.

Changes in Version 2.0 (2017-01-18)

  • redcapDbConnection methods are being deprecated. To our knowledge, no one is using these methods, and we do not believe they would work as previously coded anyway. The methods definitions continue to be reserved although they will likely not be developed in the forseeable future (if at all). Please file an issue on GitHub if you feel such methods would be of use.
  • redcapProjectInfo is being deprecated, as it will inevitably create confusion with the API method exportProjectInformation. The replacement function is exportBundle.
  • export bundles are now placed into the option redcap_bundle by default. For now, exportBundle will also return that same object. This is to prevent back-compatibility problems with existing code, but will change at a future date.
  • Added several new API functions. All functions up to REDCap 6.5.0 are included.
  • Optional arguments that previously had no default now default to NULL. There should be no change in behavior related to this change.
  • Further standardization to documentation. Each function has three new sections: "From the REDCap Documentation" which gives the description of the function as taken from the REDCap documentation; "REDCap Version" which gives the versions of REDCap for which the function is known to operate; and "Known REDCap Limitations" which documents any bugs or other limitations that may be encountered when working with the API
  • the fieldToVar function now operates on a switch statement instead of a sequence of if else blocks. It also incorporates a for loop in place of the lapply and <<- structure.
  • Error checking, when feasible, makes use of the checkmate package.
  • exportVersion will now return "5.12.2" for all versions of REDCap less than 6.0.0. While it is admittedly odd, this allows for consistent logical comparisons of of versions and allows better control of the package's behavior over multiple versions of REDCap.
  • REDCap variables that can reasonably be treated as factors are given an additional class, redcapFactor, that inherits whatever class the variable becomes on export. For example, if factors = TRUE, the new class will be c("redcapFactor", "factor"), otherwise, it may be something similar to c("redcapFactor", "numeric"). This is done to assist in converting factors back and forth between classes as needed (particular when using redcapFactorFlip).
  • An package option is added for how to manage errors returned by the API. This is used to assist in dealing with errors relating to bugs in the API and/or the user's version of REDCap. For instance, if an API method doesn't exist for the user's version of REDCap, the user can control if a hard error is returned, or if a NULL value is returned. See ?redcap_error for details.
  • Codebase has been standardized and given a cleaner format (yeah, that's totally subjective)

Changes in Version 1.3.5 (2017-01-20)

  • Bug fixes from @tobadia. (Issue #79)

Changes in Version 1.3.2 (2015-12-09)

  • Bug fix. Changed the call to fieldToVar in exportReports; was incorrectly referencing the meta_data field names. Thanks to Will Campbell for finding this bug.

Changes in Version 1.3.1 (2015-07-05)

  • Changed the default config argument in redcapConnection from config=list() to config=httr::config().
  • Added code to allow all errors from apiCall to be returned correctly.

Changes in Version 1.3 (2015-03-04)

  • The Maintainer has been changed to Stephen Lane
  • Bug fix: The REDCap API Error message for exportEvents, exportArms, and exportMappings changed between versions 5.x and 6.0. In 5.x, the error message is "You cannot export arms for classic projects." In 6.0+, it is "ERROR: You cannot export arms for classic projects." The change causes exportEvents, exportArms, and exportMappings to cast an error instead of returning the character string with the error. The bug fix accomodates the error messages from both 5.x and 6.0+.

Changes in Version 1.2 (2015-02-01)

  • Code has been rewritten to make use of the roxygen2 documenation style.
  • The function 'allocationTable' is added. This assists in producing allocation tables for the randomization module.
  • Offline versions for 'exportRecords' and 'allocationTable' are included. These produce output identical to the API calls, but operate based on the csv's downloaded via the user interface.

Changes in Version 1.1 (2014-10-01)

  • redcapAPI now depends on R 3.0.0 or higher
  • A bug fix was added. When specifying the 'fields' and 'forms' arguments in 'exportRecords', only the variables in 'fields' were being converted to the appropriate data types. This has been corrected.
  • redcapAPI requires Hmisc 3.14-6 or higher. This is a consequence of the following item. Please update your Hmisc package.
  • The Hmisc package was moved from the Suggests field to the Imports field. This reflects the addition of some of the label functions in Hmisc being explicitly exported, making them available to import.

Changes in Version 1.0.1 (2014-10-20)

  • Bug fix: in importRecords meta data was not previously exported when a project info object was not provided. This is now corrected
  • Bug fix: in exportRecords and exportReports, the checkbox labels weren't being returned as factor levels when checkboxLabels=TRUE. The behavior is now consistent with expectations.
  • Bug fix: in compareRedcapVersion, a logical check was failing due to an ommitted argument in grepl. This has been corrected.
  • added function apiCall. This wraps a call to tryCatch. If a Gnu/TLS recv error is returned, the encoding is changed from 'gzip' to 'identity' to successfully retrieve the API response.
  • tryCatch calls are added to redcapProjectInfo to prevent fatal errors when one of the API functions casts an error. The output is modified to indicate where the problem occurred. This is most likely to affect exportUsers. An unresolved issue behind this is logged in the issues on Github.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


2.3 by Benjamin Nutter, 2 years ago,,

Report a bug at

Browse source code at

Authors: Benjamin Nutter [aut, ctb, cre] , Stephen Lane [ctb] , Will Beasley [ctb] , Jeffrey Horner [ctb] , Will Gray [ctb] , Jeremy Stephens [ctb] , Marcus Lehr [ctb]

Documentation:   PDF Manual  

Task views: Web Technologies and Services

GPL-2 license

Imports checkmate, chron, DBI, httr, labelVector, lubridate, readr, stringr, tidyr

Imported by ReviewR, rccola.

Suggested by tidyREDCap.

See at CRAN