Skip to content

Data Import Overview

Data Import Overview

Article ID RC-IMP-01 — Data Import Overview
Domain Data Import
Applies To All REDCap project types; requires Project Design and Setup rights for instrument/metadata imports; requires Data Entry rights for record data imports
Prerequisite RC-FD-01 — Form Design Overview; RC-NAV-UI-01 — Project Navigation UI
Version 1.8
Last Updated 2026-04-10
Author See KB-SOURCE-ATTESTATION.md
Related Topics RC-FD-04 — Instrument Library & Zip Files; RC-FD-03 — Data Dictionary; RC-DE-01 — Record Creation & the Record Home Page; RC-NAV-UI-02 — Project Menu Reference; RC-NAV-REC-01 — Record Navigation Overview

1. Overview

REDCap provides multiple mechanisms for importing both metadata (project structure, instruments, settings) and data (participant records). This article provides a comprehensive overview of the available import features, the file formats they use, and how to navigate to each one. It is intended as a starting point for users who want to understand the full landscape of REDCap's import capabilities before working with any specific feature in depth.

This article assumes: - You are logged into a REDCap instance. - Your example project has surveys, longitudinal mode, and Data Access Groups (DAGs) disabled unless otherwise noted. - Your user account has at minimum Project Design and Setup rights.

2. Key Concepts & Definitions

Data Import Tool

A built-in REDCap application that allows bulk importing of participant record data from a CSV or XML file. Accessible from the project's Applications menu. Not to be confused with instrument import features, which import project structure rather than participant data.

Metadata

In REDCap's context, metadata refers to the project's structure — its instruments, variables, field types, validation rules, survey settings, and longitudinal configuration. Metadata does not include participant data. The distinction matters because REDCap offers separate import mechanisms for metadata vs. data.

CSV (Comma-Separated Values)

A plain-text file format where each row is a record and each column is separated by a delimiter (usually a comma). Compatible with any spreadsheet application (Excel, Google Sheets, etc.). The most common format for bulk data imports in REDCap because any REDCap data export in CSV format can be re-imported directly.

XML / CDISC ODM

XML (Extensible Markup Language) is a structured, human-readable format used for data exchange. REDCap uses the CDISC ODM (Operational Data Model) XML standard for project backups and full project transfers, including both metadata and data. CDISC ODM is a vendor-neutral format designed for archival and interchange of clinical data.

Zip File

A compressed archive file. In REDCap, zip files are used exclusively for importing and exporting individual instruments (forms). REDCap only accepts zip files generated by another REDCap project — zip files from other sources are rejected.

Coordinate Variable

A column in a CSV import file that tells REDCap where a data point belongs within the project structure, beyond just the Record ID. Required for longitudinal projects (event name), repeated instruments (repeat instrument name and instance number), and DAG-assigned users (DAG name). Without the correct coordinate variables, the import will fail or map data to the wrong location.

Record ID

The unique identifier for each participant record in a REDCap project. Always the first column in any CSV import file. The variable name may differ across projects (e.g., record_id, participant_id, patient_id) — use the variable name as it appears in your specific project.

Delimiter

The character used to separate values in a CSV file. The REDCap default is a comma, but tab and semicolon are also supported. The delimiter selected in the Data Import Tool must exactly match the delimiter used in the file being uploaded — a mismatch causes import errors or incorrect data mapping.

Blank Values Overwrite

An import setting that controls whether empty cells in the upload file overwrite existing data in REDCap. When set to Yes, a blank cell replaces a stored value with nothing. The default is No. This setting should only be changed to Yes when blanking out existing data is intentional.

3. File Formats Used in REDCap

REDCap uses three main file formats for importing forms and data.

3.1 Zip Files

Zip files combine and compress a series of other files into a single archive. In REDCap, zip files are used to import and export individual instruments (forms). REDCap only accepts zip files that were generated by another REDCap project. Zip files from other sources will be rejected.

See RC-FD-04 — Instrument Library & Zip Files for full coverage of zip file import and export.

3.2 XML Files (CDISC ODM)

XML (Extensible Markup Language) is a versatile, human-readable format used for structured data exchange. REDCap uses the CDISC ODM (Operational Data Model) XML standard — a vendor-neutral, platform-independent format designed for the interchange and archival of clinical and research data.

REDCap uses CDISC ODM XML in two contexts:

  • Project backups and restores — exporting and recreating entire projects, including metadata and data (see Section 7).
  • Record data import — importing participant data from a REDCap ODM export or from another ODM-compatible system outside of REDCap (see Section 8.4).

Version requirement: REDCap only accepts ODM version 1.3.X. Files produced by other ODM versions may not import correctly.

Note: The REDCap API can also use XML files for data transfer, but this is an advanced feature outside the scope of this article.

3.3 CSV Files

CSV (Comma-Separated Values) files are plain-text spreadsheet files compatible with any spreadsheet application (e.g., Microsoft Excel, Google Sheets). CSV files are the most commonly used format for bulk data imports in REDCap because any REDCap data export in CSV format can be re-imported into the same project.

By default, a comma is used as the delimiter. However, REDCap also supports alternative delimiters such as tab or semicolon. These alternatives are sometimes required due to regional differences in number formats. Using the correct delimiter is important — REDCap will reject a file if the selected delimiter does not match its actual format.

Note: The REDCap API additionally supports JSON files for data transfer, but this is an advanced feature outside the scope of this article.

4. REDCap Shared Library

The REDCap Shared Library is a centrally maintained collection of instruments curated by Vanderbilt University and the REDCap consortium. It allows you to import validated clinical and research instruments directly into your project without building them from scratch.

This feature is fully covered in RC-FD-04 — Instrument Library & Zip Files, Section 3.

5. Zip File Instrument Import

Zip files allow you to export an instrument from one REDCap project and import it into another. This is useful for reusing instruments across projects or sharing them with collaborators at other institutions.

This feature is fully covered in RC-FD-04 — Instrument Library & Zip Files, Section 4.

6. Project Creation Templates

Every REDCap installation comes with a set of pre-loaded project templates. These range from simple projects with a few instruments to complex longitudinal databases with multiple arms. Templates are a useful way to explore what a REDCap project looks like before building your own.

6.1 How to Load a Template

1 Navigate to Create a New Project.
2 Select the "Use a template" option.
3 Browse the available templates and select one.
4 Fill out the remaining required fields (project title, purpose, etc.).
5 Click Create Project — or Submit a Project Request, depending on your institution's REDCap configuration.

Note: Your REDCap administration team can add custom templates specific to your institution. This is especially useful if there is a frequently used base project structure at your organization.

7. Project Backup & Restore

REDCap provides a built-in project backup feature that allows you to export your entire project as an XML file. This is useful if you want to move a project to a different REDCap installation or keep your own backup independent of system-wide backups.

7.1 Backup Options

The backup feature offers two distinct options:

  • Metadata only — Exports the project's structure only: instruments, variables, survey settings, reports, and longitudinal setup. No participant data is included. Use this option to clone a project's design in a different REDCap instance.
  • Metadata & data — Exports the full project structure and all captured participant data. Use this option to move an entire project, including its records.

Important: When moving a project using this method, user accounts and survey distribution links are typically not carried over — these are installation-specific. Use caution when moving a project that is actively collecting data via surveys, as survey links in the original installation will no longer function after the move.

7.2 Creating a Backup

1 Navigate to Project Setup → Other Functionality → "Copy or back up the project".
2 Select either Metadata only or Metadata & data.
3 A backup XML file will begin downloading to your downloads folder.

7.3 Restoring a Project from Backup

1 Navigate to Create a New Project.
2 Under Project creation option, select "Upload a REDCap project XML file (CDISC ODM format)".
3 Click Select XML file and choose your backup file. (Pro tip: you can drag and drop the file directly onto the Choose File button.) After a valid file is selected, REDCap displays the Source REDCap version and File creation date from the XML — verify these match the export you intended to restore.
4 Fill out the remaining required fields (project title, purpose, PI name).
5 Click Create Project — or Submit a Project Request, depending on your REDCap installation's configuration.

Note: If REDCap displays "This file does not appear to be a valid REDCap project XML file," the upload was rejected. Common causes: the file is not in CDISC ODM format, it is corrupted or truncated, or it was exported from an incompatible REDCap version. Re-export from the source project and try again.

8. Data Import Tool

The Data Import Tool allows you to import participant record data in bulk. REDCap supports several bulk import methods:

CSV import is the recommended method for most users because any REDCap data export in CSV format can be used directly as an import file in the same project, and CSV files are easy to modify in a spreadsheet editor. The XML/ODM import option is useful when transferring data from another ODM-compatible system, or when working with a REDCap ODM export — see Section 8.4 for the ODM import workflow.

8.1 Uploading a CSV Data File

1 Navigate to Project → Applications menu → Data Import Tool. If you do not see this option, check your user rights.
2 Review and confirm the import settings before uploading. The available settings are described in the table below. In most cases, the standard settings are correct — but always verify the delimiter matches your file and confirm the date format.
3 Select your CSV file. (Pro tip: you can drag and drop the file directly onto the "Choose File" button.)
4 Click the "Upload File" button.
5 REDCap processes the file and displays a results preview.
6 Review the results window carefully for any errors or warnings. If issues are found, click Cancel, fix the CSV file, and upload again. If everything looks correct, scroll down and click the "Import Data" button to commit the upload.

Important: Clicking "Upload File" does not import the data — it only stages a preview. The data is not saved to the project until you click "Import Data" at the bottom of the results screen. This is the most common reason users do not see their records after uploading.

Import Settings Reference

Setting Options Notes
Import mode Real time / Background process Real time imports complete immediately in the browser. Background imports run asynchronously — better for large files, but may take longer overall. REDCap emails you when the background import finishes. See Section 8.3 for error handling in background mode.
Display data comparison table Yes / No When Yes, REDCap displays a side-by-side comparison of uploaded values vs. existing values before you commit the import. For records that already exist, the table shows the current stored value alongside the new value that will overwrite it — useful for catching unexpected changes before they are committed. The downside is that rendering the table can be slow for large imports. Disable this option when importing a large number of values and you are confident the file is correct.
Overwrite data with blank values No (default) / Yes When Yes, empty cells in the import file overwrite and erase existing stored values in the project. Leave at No unless you specifically intend to clear data — with No, blank cells are ignored and existing values are preserved.
CSV delimiter Comma / Tab / Semicolon (pipe \| and caret ^ are also accepted when importing via the API — see RC-API-02) Must match the actual delimiter used in your file.
Date format MM/DD/YYYY or YYYY-MM-DD / DD/MM/YYYY or YYYY-MM-DD Must match how dates are formatted in your file. Both US and European date formats are supported.
Records formatted as Rows (default) / Columns Controls whether records run across rows or down columns. Rows is the standard format. The Data Import Template can be downloaded in either format.

8.2 Background Import and Error Handling

When the background import option is selected, REDCap processes the file asynchronously rather than in the browser. This is better suited for large data files, though it may take longer to complete overall than a real-time import of the same file. REDCap sends an email notification when the import finishes.

If any rows fail during a background import, REDCap reports the errors and provides the option to re-download only the rows that failed. You can then fix the errors in that subset file and re-import it without reprocessing the rows that already imported successfully.

Background imports in progress or recently completed can be reviewed via the View background imports link at the top of the Data Import Tool page. Each background import appears as its own row in the table, with the following columns:

Column Description
Status Current state of the import (e.g., in progress, completed, failed)
Upload time When the file was submitted
Completion time When the import finished processing
Original filename The name of the uploaded file
Uploader The REDCap user who submitted the import
Records provided Total number of records in the uploaded file
Records imported Number of records successfully imported
Total import time (minutes) How long the import took to complete
Errors Number of records or rows that failed to import

8.3 Partial vs. Full Uploads

The Data Import Tool supports both full and partial uploads. You can import all records in a single file, a single data point for a single record, or anything in between. The structure of your CSV file determines what gets imported. See Section 9 for details on how to build and modify a CSV upload file.

8.4 CDISC ODM (XML) Import

REDCap can import record data from a CDISC ODM XML file produced by a REDCap export or by another ODM-compatible system. The file must conform to ODM version 1.3.X.

1 Navigate to Project → Applications menu → Data Import Tool, then select the CDISC ODM (XML) import tab.
2 Click Browse or Choose File to select the ODM XML file on your computer.
3 Set the Overwrite data with blank values option as appropriate (see Import Settings Reference in Section 8.1).
4 Click Upload File.
5 REDCap checks the file for errors and displays the data for review — the data is not immediately imported. Review for any errors or warnings.
6 If the data looks correct, click Import Data to commit. If errors are found, click Cancel, correct the file, and upload again.

Note: Unlike the CSV import, the ODM import does not offer a background processing option. The import runs in real time in the browser.

9. Modifying a CSV Upload File

A valid CSV upload file must always contain the following:

  • Header row — The first row of the file, containing the REDCap variable names for every column you are uploading.
  • Record ID column — The first column. This variable may be renamed in your project (e.g., participant_id, patient_id), but it is always required.
  • At least one data point — A row with at least one non-empty value.
  • Correct data formats — Each value must match the variable type it maps to (e.g., dates in a date field, numbers in a numeric field). Mismatched formats cause import errors.
  • Raw coded values for multiple choice fields — Dropdown, radio, and checkbox fields must contain the raw coded value (e.g., 1, 2, 3), not the choice label (e.g., "Yes", "No", "Unknown"). REDCap cannot process choice labels and will reject rows containing them. The coded values for each field are listed in the project's Codebook (accessible from the left-hand menu).

For a basic project, these five elements are sufficient for a working upload file.

9.1 Coordinate Variables

If your project uses features beyond the basic setup, you will need additional coordinate variables in your CSV file. Coordinate variables tell REDCap exactly where a data point belongs within the project structure.

Coordinate Variable When Required
Record ID Always required
Event ID (unique event name) Required for longitudinal projects. The value follows the format uniqueeventname_arm_N — for example, baseline_arm_1 or followup_arm_2. Find all unique event name values for your project in Project Setup → Define My Events. The unique event name is shown in the "Unique event name" column of that page.
Repeat Instrument Required when uploading data for a repeated instrument. Leave this column empty when the row contains data for a repeating event (as opposed to a repeating instrument within a non-repeating event).
Repeat Instance Required when uploading data for a repeated instrument or a repeated event; specifies which instance number. When redcap_repeat_instrument is empty but redcap_repeat_instance has a value, REDCap interprets the row as belonging to a repeating event. When redcap_repeat_instrument is filled, REDCap interprets the row as a specific instance of a repeating instrument within the event.
Data Access Group (DAG) Optional if the uploading user is not assigned to any DAG; required if the uploading user belongs to one or more DAGs

Tip — Auto-numbering repeating instances: When importing data for a repeating instrument or repeating event, you do not need to determine how many instances already exist before importing. Set the redcap_repeat_instance column value to new for any row you want REDCap to assign the next available instance number automatically. This avoids overwrite errors caused by instance number conflicts.

Instructions for working with event IDs, repeated instruments, and repeated instances are outside the scope of this article.

9.2 Finding the Correct Header Row for Your Project

Two methods are available to determine what coordinate variables and column headers your project requires:

  • Download the Data Import Template from within the Data Import Tool. The template contains no data rows — it is a header-only file with the correct column names for your project's current setup, including all required coordinate variables.
  • Do a full data export from the Data Exports, Reports & Stats application. The export uses the exact same header structure as the Data Import Template and can be used directly as an import file. If records already exist in the project, the export will also contain example data showing how correctly formatted values look.

9.3 Multi-Row Structure in Longitudinal and Repeating Projects

In a basic project, each record occupies a single row in the import file. In longitudinal projects and projects with repeating instruments, a single record spans multiple rows — one row per event, and one row per repeating instrument instance. Each row carries only the data for that specific location in the project structure.

The table below shows how rows are structured for a record that has one regular event and two repeating instruments:

record_id redcap_event_name redcap_repeat_instrument redcap_repeat_instance Notes
P001 baseline_arm_1 (empty) (empty) Regular event data for this record
P001 baseline_arm_1 visits 1 First instance of the "visits" repeating instrument
P001 baseline_arm_1 visits 2 Second instance of the "visits" repeating instrument
P001 baseline_arm_1 lab_results 1 First instance of "lab_results" repeating instrument

Key points: - Rows where both redcap_repeat_instrument and redcap_repeat_instance are empty contain regular (non-repeating) event data. - Rows where redcap_repeat_instrument is filled and redcap_repeat_instance has a number contain data for a specific instance of a repeating instrument within a non-repeating event. - Rows where redcap_repeat_instrument is empty but redcap_repeat_instance has a number indicate that the entire event is repeating — not just a single instrument within it. - The redcap_repeat_instance value is a sequential integer starting at 1. To add a new instance without pre-counting existing ones, use new as the value (see the auto-numbering tip in Section 9.1). - It is normal for most cells in a given row to be empty — each row only needs the columns relevant to that event or instrument instance.

9.4 Best Practice for New Importers

If you are new to importing data, create a copy of your target project and run your import tests in the copy first. This lets you fine-tune your file without affecting an active project.

10. Other Import Features

Several other areas of REDCap support file-based import and export of metadata and configuration settings. Each has its own file format and instructions — always read the on-screen instructions carefully before using these features.

Feature Location in REDCap
Events Define My Events
Arms Define My Events
Instrument–Event Mappings Designate Instruments for My Events
Alerts & Notifications Alerts & Notifications
Language Setups Multi-Language Management module
Survey Settings Survey Settings
Logging Logging (download only — upload not supported)
User Rights & Roles User Rights
Data Access Group Assignments Data Access Groups
Data Quality Rules Data Quality

REDCap is actively developed; Vanderbilt adds new functionality regularly, including new import/export file types. If a feature is not listed here, check the relevant module for import/export options.

For a detailed, field-by-field reference of every CSV upload option listed above — including column formats, upload behavior, and navigation paths — see RC-IMP-03 — CSV Upload Reference: All Bulk Upload Options in REDCap.

11. Common Questions

Q: How do I import participant data into REDCap in bulk?

A: Use the Data Import Tool, accessible from the project's Applications menu. Prepare your data as a CSV file with a header row of REDCap variable names and a Record ID column. Upload the file, review the preview for errors, then click "Import Data" to commit. Any REDCap data export in CSV format can be used directly as an import file.

Q: Why didn't my records appear in REDCap after I uploaded my CSV file?

A: The most common reason is clicking "Upload File" without completing the second step. Uploading stages a preview only — the data is not saved until you scroll to the bottom of the results screen and click "Import Data."

Q: What column headers does my CSV import file need?

A: At minimum, the header row must include the Record ID variable name (as named in your specific project). For longitudinal projects, you also need the unique event name column. For repeated instruments, you need repeat instrument and repeat instance columns. The easiest way to get the correct headers is to download the Data Import Template from within the Data Import Tool, or to export existing data from the project.

Q: How do I move a REDCap project from one server to another?

A: Use the Project Backup feature. Navigate to Project Setup → Other Functionality → "Copy or back up the project" and export as Metadata & data (XML). Then create a new project on the destination server using the "Upload a REDCap project XML file" option. Note that user accounts and survey links are not transferred — these are installation-specific.

Q: Can I import just a few fields or a single record, or does the import have to be the whole project?

A: Partial imports are fully supported. Your CSV file only needs to include the Record ID and the specific variables you are updating. REDCap will import only the columns present in the file and leave all other data unchanged.

Q: What is the difference between "Metadata only" and "Metadata & data" in the backup options?

A: Metadata only exports the project's structure — instruments, variables, survey settings, reports — with no participant data. Metadata & data exports everything, including all collected records. Use Metadata only to clone a project's design; use Metadata & data to migrate or archive an entire project with its records.

Q: My import file has dropdown and radio values as text labels (like "Yes" or "Male") — will that work?

A: No. REDCap requires raw coded values (e.g., 1, 0, 2) for all multiple choice fields — dropdowns, radios, and checkboxes. Choice labels are not accepted and will cause the import to fail for those rows. To find the correct coded values for each field, open the project Codebook from the left-hand menu. Alternatively, export existing data from the project — the export file uses raw codes and is formatted as a valid import file.

Q: How do I import an instrument from another REDCap project?

A: Export the instrument as a zip file from the source project (Online Designer → Instrument Actions → Download instrument zip), then import it into the target project via the Online Designer's Upload button. See RC-FD-04 — Instrument Library & Zip Files for the full workflow.

12. Common Mistakes & Gotchas

Clicking "Upload File" but not "Import Data." The upload step only stages a preview — data is not saved until you scroll down and click "Import Data." If you navigate away after uploading without clicking Import Data, nothing is imported. This is the single most common import support question.

Selecting the wrong delimiter. If the delimiter selected in the Data Import Tool does not match the actual delimiter in your CSV file, REDCap may reject the file outright or, worse, misread the columns and map data to the wrong variables. Always confirm the delimiter before uploading — open your file in a text editor if unsure.

Setting "Blank values overwrite" to Yes unintentionally. When this setting is Yes, any blank cell in your import file overwrites the existing stored value with nothing. This can silently erase real participant data if your file has empty cells in columns that already have data in REDCap. The default is No; only change it when you deliberately intend to clear existing values.

Missing coordinate variables for longitudinal or repeated projects. Importing into a longitudinal project without the event name column, or into a project with repeated instruments without the repeat instrument and repeat instance columns, will cause import errors or map data to the wrong event or instance. Download the Data Import Template from the tool to confirm which coordinate variables your project requires.

Using the wrong date format. If the date format selected in the import settings does not match how dates are formatted in your CSV file, REDCap will either reject the rows with date errors or import the dates incorrectly. For example, selecting MM-DD-YYYY when your file uses YYYY-MM-DD will cause mismatches. Confirm the date format in your file before uploading.

Using choice labels instead of raw coded values for dropdown, radio, or checkbox fields. REDCap only accepts the numeric or text code assigned to each choice — not the human-readable label. For example, if a Yes/No field is coded as 1=Yes | 0=No, the import file must contain 1 or 0, not Yes or No. Using labels causes those rows to fail. Look up the correct codes in the project Codebook before building your import file.

Importing a zip file from a non-REDCap source. REDCap only accepts zip files for instrument import if they were generated by another REDCap project. Zip files created manually, from other software, or from other sources will be rejected. If you need to import an instrument from outside REDCap, use the Data Dictionary CSV method instead.

API Access

Note: The following REDCap API methods provide programmatic access to this functionality. API usage is an advanced feature that requires knowledge of computer programming or access to a developer resource. See RC-API-01 — REDCap API for authentication, token management, and setup.