REDCap API Guide 2026: Python, R, FHIR and EHR Links
CTO & Co-Founder
CTO & Co-Founder at Nirmitee.io. Architects healthcare integrations across FHIR, SMART on FHIR, ABDM and NHCX, writing from production experience taking hospital software from sandbox to go-live.

REDCap is the research data capture software made at Vanderbilt in 2004. It is not one cloud service. Each institution licenses it, installs it and runs it, and "each system is independently maintained and supported". That one fact shapes every REDCap integration. The REDCap API, the FHIR link to an EHR and any external module all depend on the local REDCap admin.
This guide is for a product lead, a research IT team or a vendor that needs data in or out of REDCap. It covers what you can integrate and every route REDCap offers. It walks through a build with curl, Python and R, and shows how to export large projects safely. It then covers REDCap next to an EHR, a warehouse and other EDCs, how to make the sync reliable, the common blockers with a fix for each, and harder cases such as mid-study changes and project moves. It quotes Vanderbilt's own pages, API documents published by named institutions, and the docs of the open-source PyCap and REDCapR clients. Where advice is our own engineering practice, we say so. If your team is building the EHR side, our EHR integration services page shows how we scope that work. Last checked: Nov 21, 2026.
REDCap API and EHR integration at a glance
| Question | Short answer |
|---|---|
| Who grants access? | The REDCap administrators of the institution that runs the system. They grant API rights, issue tokens and enable CDIS. |
| Who signs? | A non-profit signs a license with Vanderbilt University to run REDCap. For CDIS, the institution's Health IT team registers the REDCap app with its EHR. |
| Are there public documents? | In part. Vanderbilt publishes the CDIS page and a technical overview. The full API help sits behind each install's login. PyCap, REDCapR and several institutions publish working examples. |
| Which routes exist? | The REDCap API, the Data Entry Trigger, CDIS (Clinical Data Pull and Clinical Data Mart over FHIR), REDCap SHARE, Dynamic Data Pull, external modules, the mobile apps and file import and export. |
| What does it cost? | The license is free to non-profits. Vanderbilt's own hosting has a monthly fee. EHR-side fees are not published. |
| How long does it take? | License review takes up to six weeks, plus up to two weeks for accounts. API token approval and CDIS set-up times are not published. |
| What is the biggest limit? | No developer license exists, and outside IT firms cannot install, maintain or support REDCap. Rate limits are set per server, and a hit bans the IP. |
What can you build on a REDCap integration?
Eight use cases follow. Each rests on a documented route and points to a row in the table of what is possible (section 7). Build complexity is our own rating. Vanderbilt publishes no build times, so this guide gives no build estimate.
1. Fill study forms with EHR data for an active trial
- Who it is for: research teams running prospective studies and clinical trials at hospitals on Epic or Cerner.
- The value: labs, vitals and medications arrive from the EHR, so coordinators stop retyping them.
- Build complexity: medium, mostly set-up and mapping.
- How well it works: supported. Clinical Data Pull imports EHR data "either manually in real time or automatically at a regular interval", and Vanderbilt names clinical trials as its best fit. See row P9.
2. Build a retrospective cohort dataset
- Who it is for: outcomes researchers and registries with a known list of patients.
- The value: one bulk pull for a date range and a list of MRNs, in place of a chart review.
- Build complexity: low to medium.
- How well it works: supported. Clinical Data Mart needs a date range, the data elements and a list of MRNs. See row P10.
3. Export study data to a warehouse or a statistics tool every night
- Who it is for: biostatistics cores, data teams, sponsors' analysts.
- The value: fresh data in R, Python or a warehouse without manual downloads.
- Build complexity: low.
- How well it works: supported. The API exports records as CSV, JSON or XML, and can return only records changed since the last run. See row P1.
4. Send patient-reported or device data into REDCap
- Who it is for: ePRO apps, remote monitoring tools, study portals.
- The value: data captured outside REDCap lands in the study record and goes through REDCap's own validation.
- Build complexity: medium.
- How well it works: supported. The API imports records and checks them like the Data Import Tool. See row P2.
5. Keep REDCap in step with another research system
- Who it is for: CTMS vendors, biobank systems, other EDCs such as Medidata Rave or Veeva Vault.
- The value: one set of study participants and one data dictionary across systems.
- Build complexity: medium.
- How well it works: supported for records, metadata, events and logs. Each institution's install can run a different version, so test against each one. See rows P1 to P4 and P8.
6. Pull data from a source system that has no FHIR
- Who it is for: institutions with a local data warehouse or an older clinical system.
- The value: study staff review and accept source data inside REDCap.
- Build complexity: high.
- How well it works: possible through Dynamic Data Pull. The host institution must build at least two web services as middleware. See row P11.
7. Add a custom workflow inside REDCap
- Who it is for: study teams with a need the standard features do not cover.
- The value: new pages, scheduled jobs or API services inside REDCap.
- Build complexity: medium to high.
- How well it works: supported through external modules, which Vanderbilt calls "the recommended way to programmatically extend REDCap's base functionality". Each institution reviews custom modules before install. See row P12.
8. Create and copy projects from a template by code
- Who it is for: research offices that set up many similar studies, or move studies between servers.
- The value: the same forms and settings every time.
- Build complexity: low to medium.
- How well it works: supported. Vanderbilt notes "an API method for creating whole new projects", and a project can be exported whole as CDISC ODM XML. See row P7.
The eight REDCap use cases compared
| Use case | Who it is for | Build complexity (our rating) | Row in the possible table |
|---|---|---|---|
| 1. EHR data into an active trial | Prospective study teams | Medium | P9 |
| 2. Retrospective cohort pull | Outcomes and registry teams | Low to medium | P10 |
| 3. Nightly export to a warehouse | Data and biostatistics teams | Low | P1 |
| 4. Patient or device data in | ePRO and monitoring apps | Medium | P2 |
| 5. Sync with another research system | CTMS, biobank and EDC vendors | Medium | P1 to P4, P8 |
| 6. Non-FHIR source system | Institutions with a warehouse | High | P11 |
| 7. Custom workflow inside REDCap | Study teams | Medium to high | P12 |
| 8. Projects from a template | Research offices | Low to medium | P7 |
How do you get access to the REDCap API, and who does what?
You ask the REDCap administrators at the institution that runs the system. Vanderbilt has no access to the thousands of other REDCap systems, so it cannot issue tokens or enable features on them. Four parties take part in almost every project.
| Role | What they do in the integration | Source |
|---|---|---|
| Institution REDCap admin | Grants API rights, approves tokens, enables CDIS, installs approved external modules, sets the rate limit and the rules for production changes. | |
| Health IT team | Enables FHIR web services and registers the REDCap app client with the EHR for CDIS. | |
| Principal investigator (PI) and study team | Owns the project and its IRB approval, sets user rights, and decides who can export identified data. CDIS checks the IRB number and key study personnel. | |
| Data manager | Builds instruments and the data dictionary, moves the project to production, submits Draft Mode changes, and checks imported data. | |
| Vendor or outside developer | Builds the outside system and calls the API with a token the institution issues. Cannot install, maintain or support REDCap itself. |
The steps for an API token
The University of Illinois REDCap team publishes these steps.
- Open the project that needs the API.
- In the left menu under Applications, click API. If the link is missing, someone with User Rights must grant you API privileges.
- Click "Request API token". The request goes to the REDCap administrative team.
- On a first request, the team sends an API agreement to complete.
- Once the token is granted, test in the API Playground.
Tokens are "at the user-project level". Three users on one project need three tokens, and one user on three projects needs three tokens. Every action taken with a token is logged as the token's user. Our advice is to run the integration under its own REDCap user with only the rights it needs, so its actions are easy to trace and survive staff changes.
The steps for CDIS with an EHR
CDIS "must be enabled by a REDCap administrator". At Vanderbilt, "our Health IT team enabled FHIR web services and registered a new FHIR App Client for CDIS with Epic". The set-up guide is a ZIP file in the REDCap Control Center, which only admins can open. Cerner guides sit there too. The project's IRB number must be active in the local IRB system, and the user must be listed as key study personnel.
If you are a software company
Vanderbilt states that "There is no 'developer partner' license", and a developer cannot have "their own REDCap license or system OR have access to a system's backend or codebase". You can test on the projectredcap.org trial system, but a trial account lasts seven days. Real work runs on a customer institution's install, with a token its admins issue. The official API help pages sit on the REDCap community site. REDCapR's authors advise that without an account you "ask your campus REDCap administrator to send you the static material".
What can you integrate in REDCap?
The API covers far more than study records. PyCap groups its methods by the same headings the REDCap API Playground uses, and each one maps to a content value sent to the server. The table lists what each part holds, the content value, and whether you can read it, write it or both.
| Part of REDCap | What it holds | API content value | Read or write | Source |
|---|---|---|---|---|
| Records | The study data, one row per record, event and repeat instance | record | Both, plus delete | |
| Data dictionary (metadata) | Fields, forms, types, choices, validation | metadata, exportFieldNames | Both | |
| Instruments | Form list, PDF of forms, form to event mapping | instrument, pdf, formEventMapping | Read, mapping both | |
| Arms and events | The visit schedule in longitudinal projects | arm, event | Both, delete only in development | |
| Repeating instruments and events | Which forms or events repeat | repeatingFormsEvents | Both | |
| Files | A file stored in a file upload field on one record | file | Both, plus delete | |
| File repository | Project-level files and folders | fileRepository | Both | |
| Users, roles and data access groups | Who can see and change what | user, userRole, userRoleMapping, dag, userDagMapping | Both | |
| Logs | Every change, export and user action | log | Read | |
| Surveys | Survey links, queue links, return codes, participant lists | surveyLink, participantList and others | Read | |
| Reports | A saved report's data set | report | Read | |
| Project information and version | Project settings, production status, REDCap version | project, version | Read |
Records, and how REDCap shapes them
A record export returns one row per record in a classic project. In a longitudinal project, or with repeating instruments, a record spreads over several rows. Asking for record_id adds three columns: redcap_event_name, redcap_repeat_instrument and redcap_repeat_instance. Those four columns together are the real key of a row. A checkbox field becomes one column per choice, named like checkbox_field___1. Each form adds a status column such as form_1_complete. A file field exports only the file name.
PyCap's own example row shows the shape:
{"record_id": "1", "redcap_event_name": "event_1_arm_1", "redcap_repeat_instrument": "",
"redcap_repeat_instance": 1, "field_1": "1", "checkbox_field___1": "0",
"checkbox_field___2": "1", "upload_field": "test_upload.txt", "form_1_complete": "2"}
Events and arms (longitudinal projects)
An arm is a separate schedule, and an event is a visit in that schedule. Event exports return event_name, arm_num, unique_event_name, custom_event_label and event_id. Use unique_event_name in code (for example event_1_arm_1), since labels can change. Arm and event methods "only work for longitudinal projects", and deleting them is allowed only in development status.
Repeating instruments
A repeating instrument lets one record hold many rows of the same form, such as several adverse events. The repeatingFormsEvents export tells you which forms and events repeat. On import, each row must carry the right redcap_repeat_instrument and redcap_repeat_instance, or the data lands on the wrong instance.
Files
File export works on one record, one field and, where needed, one event and repeat instance per call. PyCap notes: "Unlike other export methods, this only works on a single record." So a bulk file pull is a loop. Plan for it in time and in rate limits.
Users, roles and logs
The user and role methods let a central team audit who has access across many projects. The log export can filter by type (exports, record adds, edits and deletes, user changes, page views), by user, by record and by time window. REDCap's built-in audit trail "logs all user activity and logs all pages viewed by every user".
Read versus write in short
Read access needs export rights. Write access needs import rights. REDCapR notes that its batched writer needs "Full Data Set" export rights, while a user with only "De-Identified" export rights can still use its one-shot writer. Ask the PI for the smallest set of rights that does the job.
What are the ways to integrate with REDCap, and when do you pick each?
| Route | What it is | Direction | Pick it when | Source |
|---|---|---|---|---|
| REDCap API | Built in. Token per user and project, form posts to the install's /api/ URL | In and out | An outside app or script moves study data, metadata or files | |
| Data Entry Trigger | REDCap sends an HTTP POST to one URL when a record or survey response is saved on a form | REDCap out (a notice) | An outside system must react soon after someone enters data | |
| CDIS: Clinical Data Pull | FHIR with OAuth2, real time or scheduled, reviewed by users | EHR into REDCap | A prospective study on Epic or Cerner | |
| CDIS: Clinical Data Mart | FHIR bulk fetch by date range, data elements and MRNs | EHR into REDCap | A retrospective study pulled in bulk | |
| REDCap SHARE | Patients authorize sharing through their EHR patient portal | EHR into REDCap | A study wants data the patient chooses to share | |
| Dynamic Data Pull (custom) | Two or more web services built by the host as middleware | Source into REDCap | A source system with no FHIR | |
| External modules | PHP modules with hooks, pages, crons and API services | Inside REDCap | Custom logic the standard features lack | |
| Scheduled exports | A job that calls the API on a timer | REDCap out | A warehouse or statistics feed | |
| REDCap Mobile App and MyCap | Offline data entry on phones and tablets, and participant-reported outcomes | Device into REDCap | Field work with poor internet, or patient surveys on a phone | |
| File import and export, project XML | Data Import Tool, exports to stats packages, CDISC ODM XML | Both | A one-off move or a project copy |
How to choose
- Start with the API. It is the only route that both reads and writes, and it needs no install. Most integrations are API jobs with one of the other routes added.
- Add the Data Entry Trigger only for speed. It tells you a record changed. It does not carry a guaranteed data set, and it is "not triggered by data imports". So treat it as a hint to call the API, and keep a polling job as the safety net.
- Use CDIS for EHR data, not the API. CDIS reads from the EHR through FHIR with the user's own EHR login. Building your own EHR to REDCap feed means a separate EHR interface, a separate approval and your own mapping.
- Use Clinical Data Mart for a fixed cohort, and Clinical Data Pull for patients who enroll over time.
- Use an external module only when the logic must run inside REDCap. It needs an admin to install it, and custom modules go through a security review.
- Use the mobile apps for data capture, not integration. External modules "cannot be used with the REDCap Mobile App", as Yale documents.
What REDCap SHARE adds
Vanderbilt describes REDCap SHARE as "a secure, institutionally governed capability that enables patient-authorized sharing". Patients choose what to share through their existing EHR patient portal, and "only data available through the patient portal can be shared". REDCap administrators run it, and availability "varies by organization". Ask your admin whether your institution offers it.
What the Vanderbilt team wrote about Epic
In its 2021 paper, the Vanderbilt team wrote that "an Epic Client App is available through the Epic App Orchard (search for 'REDCap')". It also wrote that local Health IT teams can add an EHR menu item that launches REDCap. Check the current Epic listing with your Epic team, since the paper describes the store as it was in 2021. For the Epic FHIR side itself, see our Epic FHIR integration guide, and for Cerner see the Oracle Health Cerner API guide.
How do you build a REDCap integration, step by step?
This is the order we follow. Steps that rest on a source carry it. The order itself is our engineering practice.
Step 1. Agree scope with the PI and the REDCap admin
Write down the project, the data that moves, its direction, how often, and who sees identified data. Ask the admin the questions in section 14 before any code. In our experience most delays come from approvals.
Step 2. Get a development project and a token
Ask for a development copy of the project, or build one from the production data dictionary. In production the API Playground lists fewer methods "so as not to affect real data". A cloned project gets no tokens, so request new ones for the copy. Ask that the token belong to a service user.
Step 3. Read the data dictionary and map fields
Export the metadata and build a field map from it. Each row of the map names the source field, the REDCap field name, the form, the event, whether it repeats, the type and the allowed values.
curl -s -X POST "https://<your-redcap-host>/api/" \
-d token="$REDCAP_TOKEN" -d content=metadata -d format=json
Then pull the events, the form to event mapping and the repeating settings for a longitudinal project. Map coded values (for example 1 = Yes) to the source system's codes. Export with rawOrLabel=raw so you work with codes, not labels.
| Map column | Why it matters |
|---|---|
| REDCap field name | Variable names cannot change in production, so they are a stable key. |
| Form and event | One form, and so one field, can sit in several events. |
| Repeat instrument | Decides how many rows one record has. |
| Type and validation | An import that breaks validation fails. |
| Choice codes | Checkbox fields export as one column per code. |
| Identifier flag | Decides what a de-identified export drops. |
Step 4. Make the first export call
The University of Oklahoma Health Sciences Center (OUHSC) BBMC publishes this request against a dummy project with fake data. We removed the token.
curl -X POST -H "Cache-Control: no-cache" \
-F "token=<YOUR_PROJECT_TOKEN>" \
-F "content=record" \
-F "format=csv" \
"https://redcap-dev-2.ouhsc.edu/redcap/api/"
The published response is status 200 with five records as CSV. The header and the first record:
record_id,name_first,name_last,address,telephone,email,dob,age,ethnicity,race,sex,height,weight,bmi,comments,demographics_complete
"1","Nutmeg","Nutmouse","14 Rose Cottage St.
Kenning UK, 323232","(432) 456-4848","nutty@mouse.com","2003-08-30",10,1,2,0,5,1,400,"Character in a book, with some guessing",2
Note the line break inside the address. Use a real CSV parser, or ask for JSON.
The same call in Python with requests. The parameter names come from the PyCap source. Lists are sent as fields[0], fields[1] and so on, the way PyCap sends them.
import os, requests
URL = "https://<your-redcap-host>/api/"
TOKEN = os.environ["REDCAP_TOKEN"] # never in the script itself
def export_records(fields=None, **extra):
data = {"token": TOKEN, "content": "record", "format": "json",
"type": "flat", "rawOrLabel": "raw", "returnFormat": "json", **extra}
for i, f in enumerate(fields or []):
data[f"fields[{i}]"] = f
r = requests.post(URL, data=data, timeout=120) # verifies SSL by default
r.raise_for_status() # 401 bad token, 403 no API rights
return r.json()
rows = export_records(fields=["record_id", "age", "demographics_complete"])
And in R with REDCapR, which batches by default.
library(REDCapR)
res <- redcap_read(
redcap_uri = "https://<your-redcap-host>/api/",
token = Sys.getenv("REDCAP_TOKEN"),
batch_size = 100L, interbatch_delay = 0.5
)
res$success; nrow(res$data)
PyCap wraps the same calls in Python. Install it with pip install PyCap and connect with Project(api_url, api_key). REDCapR 1.7.0 and redcapAPI 2.12.0 are on CRAN. Community developers maintain these libraries. Vanderbilt does not. Check that the version you pick supports the REDCap version your institution runs.
Step 5. Make the first import call
Health Research BC publishes an import in PHP with these fields.
$data = array(
'token' => '<YOUR_PROJECT_TOKEN>',
'content' => 'record',
'format' => 'json',
'type' => 'flat',
'overwriteBehavior' => 'normal',
'data' => '[{"record_id":"11","redcap_event_name":"event_1_arm_1","redcap_repeat_instrument":"","redcap_repeat_instance":"","age":"1","demographics_complete":"2"}]',
'returnContent' => 'count',
'returnFormat' => 'json'
);
// POST to https://<your-redcap-host>/api/ with CURLOPT_SSL_VERIFYPEER set to true
The import options that matter, from the PyCap source:
| Option | Values | What it does |
|---|---|---|
overwriteBehavior | normal or overwrite | overwrite erases stored values for fields you send blank. normal leaves them. |
returnContent | count, ids, nothing | ids returns the record ids written, which you need for reconciliation. |
dateFormat | YMD, MDY, DMY | "No other formattings are allowed." |
forceAutoNumber | true or false | REDCap assigns new record ids when auto-numbering is on. |
A field name that is not in the project returns an error. REDCapR's example drops calculated fields such as age and BMI before writing, and shows an invalid phone number making the whole write fail. So remove calculated fields and validate values against the data dictionary before you send.
Step 6. Validate in development
Run the export and import against the development project with test data. Compare counts and a sample of values with the source. Check the log export for what your service user did. Use the API Playground to compare your call with the server's own result. Note that its "Execute Request" button acts on real project data.
Step 7. Move to production
Ask the admin for a production token for the service user. Confirm the rate limit and any change rules. Run the first production export read only. Then turn on writes with a small batch and check it by hand.
Step 8. Go live and hand over
Schedule the job, turn on alerts (section 9), and write down who owns the token, who rotates it, and who to call when REDCap is upgraded.
Getting notified when data changes: the Data Entry Trigger
The Data Entry Trigger makes REDCap send "a HTTP Post request to the specified URL" "whenever any record or survey response has been created or modified". Its purpose is "notifying other remote systems outside REDCap". Treat it as a notice. Your service then calls the API to export the data it needs. Records loaded by import do not fire it. Read the field list for your version in your install's own help before you build the listener.
CDIS Clinical Data Pull with Epic or Cerner
- Health IT enables FHIR web services and registers the REDCap app client with the EHR.
- The REDCap admin enables CDIS and follows the set-up ZIP in the Control Center.
- The project is checked for an active IRB number and key study personnel.
- The first time a clinician opens REDCap from the EHR, CDIS asks them to log in to REDCap to link the two accounts. OAuth2 refresh tokens keep the link alive. Our note on SMART on FHIR OAuth2 for clinical apps explains that flow.
- Users enter an MRN or create the record from the EHR, and CDP pulls the mapped data.
- Users review and accept the data before it is saved.
Dynamic Data Pull for a non-FHIR source
The host institution builds at least two web services as middleware between REDCap and the source system. REDCap calls them when an identifier is entered, and a daily cron job fetches new data. Since outside firms cannot support REDCap itself, those web services belong to the institution's own team, or to the source system side of the build.
What is possible with a REDCap integration?
| Row | Function | Read or write | Route | Source |
|---|---|---|---|---|
| P1 | Export records as CSV, JSON or XML, filtered by records, fields, forms, events, logic or change date | Read | API | |
| P2 | Import records with validation, normal or overwrite mode | Write | API | |
| P3 | Export and import the data dictionary, arms, events and repeating settings | Both | API | |
| P4 | Export and import files on a record, and the file repository | Both | API | |
| P5 | Export saved reports by report id | Read | API | |
| P6 | Export and import users, roles and data access groups | Both | API | |
| P7 | Create a whole new project, or export one as CDISC ODM XML | Write / Read | API | |
| P8 | Export the project log, filtered by type, user, record and time | Read | API | |
| P9 | Pull EHR data in real time or on a schedule, create records from the EHR, fetch by MRN | Read from EHR | CDIS Clinical Data Pull | |
| P10 | Bulk fetch by date range, data elements and MRN list | Read from EHR | CDIS Clinical Data Mart | |
| P11 | Pull from a non-FHIR source, with user review and a daily cron | Read from source | DDP | |
| P12 | Add pages, hooks, crons and API services | Extend | External modules | |
| P13 | Notify an outside URL when a record or survey response is created or changed on a form | Notify | Data Entry Trigger |
CDIS can import these EHR data groups: demographics, current problems, medications (active, completed, on-hold and stopped), allergies, vital signs, laboratory results, research-related adverse events, gestational age and birth weight, encounters, immunizations, appointments, scheduled surgeries, dental findings, genomics, infections, medical history, reason for visit, insurance coverage, implants, procedures and clinical notes.
How do you export REDCap data, fully or incrementally?
Full export versus incremental export
A full export pulls every record each run. It is simple and right for small projects and for a weekly check. An incremental export asks only for records "created or modified after a given datetime" through dateRangeBegin, with dateRangeEnd as the upper bound. The values go as YYYY-MM-DD HH:MM:SS.
Three rules make incremental exports safe. These are our engineering practice.
- Save the time you asked up to, not the time the job ended. Set
dateRangeEndto the start of the run and save that value as the next run'sdateRangeBegin. - Overlap a little. Start each window a few minutes before the saved time, and let your upsert drop duplicates.
- Run a full export on a schedule (for example weekly) and compare it with your copy. It catches deletes, which an incremental window does not show, and anything the window missed.
Deleted records do not appear in a changed-since export, since there is no row left to return. The log export can filter on record_delete events in the same window, so read it to find deletes.
from datetime import datetime, timedelta
def incremental(last_end: datetime):
begin = last_end - timedelta(minutes=5) # small overlap
end = datetime.now().replace(microsecond=0)
rows = export_records(dateRangeBegin=begin.strftime("%Y-%m-%d %H:%M:%S"),
dateRangeEnd=end.strftime("%Y-%m-%d %H:%M:%S"))
deletes = requests.post(URL, data={"token": TOKEN, "content": "log", "format": "json",
"logtype": "record_delete", "beginTime": begin.strftime("%Y-%m-%d %H:%M"),
"endTime": end.strftime("%Y-%m-%d %H:%M")}, timeout=120).json()
return rows, deletes, end # save `end` only after a good load
Check the time zone. REDCapR notes that survey timestamps follow "the time and timezone of the REDCap server". Use the server's zone for the window.
Filters
| Filter | Key | Example | Source |
|---|---|---|---|
| Records | records[0], records[1] | records[0]=101 | |
| Fields | fields[0] | fields[0]=age | |
| Forms | forms[0] | forms[0]=demographics | |
| Events | events[0] | events[0]=baseline_arm_1 | |
| Logic | filterLogic | [age] > 17 | |
| Change window | dateRangeBegin, dateRangeEnd | 2026-11-20 00:00:00 | |
| Site | exportDataAccessGroups=true adds the DAG column | Only when the token user is not in a DAG |
When you filter by form, REDCap does not add record_id unless you ask for it. PyCap adds it for you. Add it yourself in raw calls.
Batching large projects
A single export of a large project can tie up the server. REDCapR's redcap_read splits the work: it pulls the record ids first, then reads 100 records per batch with a half second pause, and joins the results. Do the same in any language:
- Export only the record id field to get the full list of ids.
- Split the list into batches (start at 100, as REDCapR does).
- Export each batch with
records[], pause between calls, and retry a failed batch alone. - Join and check the total against the id list.
ids = [r["record_id"] for r in export_records(fields=["record_id"])]
ids = list(dict.fromkeys(ids)) # one id per record
for i in range(0, len(ids), 100):
chunk = {f"records[{n}]": rid for n, rid in enumerate(ids[i:i+100])}
rows = call_with_retry(lambda: export_records(**chunk)) # see section 9
load(rows)
time.sleep(0.5)
Formats
| Format | Use it for | Note |
|---|---|---|
| JSON | Code and pipelines | Easiest to parse. One object per row. |
| CSV | Statistics tools and quick checks | Text values can contain line breaks. |
| XML | Systems that want XML | Same data as JSON. |
| CDISC ODM XML (project XML) | Copying a whole project with or without data | "all records, events, arms, instruments, fields, and project attributes" |
| Stats packages | SPSS, SAS, Stata, R through the Data Export Tool | User interface route. |
Use type=flat for one row per record and event. Use raw values and raw headers in pipelines, and labels only for human reports. For data you plan to import again later, REDCapR recommends blank values for grey (never opened) form status fields.
File fields
The record export gives only the file name. Loop over the records that have a value and call the file export for each one, with record, field, event and repeat_instance. Store the file under a key built from those four values. File exports count against the same rate limit, so pace them.
Reports
A report built on the project's "Data Exports, Reports, and Stats" page can be exported by its report_id. This suits a team that wants the data manager to control the columns and filters in REDCap. The trade-off is that someone can edit the report and change your feed without notice. Pin a check on the column list.
How do you make a REDCap integration reliable?
Vanderbilt and the institution guides document the errors. The retry and reconcile design below is our engineering practice, built on those documented behaviors.
Error responses
| Status | Meaning | What to do | Source |
|---|---|---|---|
| 200 | OK | Check the body. An import can still report an error key. | |
| 400 | Bad request | Fix the call. Do not retry as is. Common causes: unknown field, bad value, bad date format. | |
| 401 | Token missing or wrong | Stop. Alert the owner. Someone rotated or deleted the token. | |
| 403 | No API permission | Stop. Ask the admin to check user rights. | |
| 404 | Not found | Check the URL ends with api/. | |
| 406 | Import formatted wrongly | Fix the payload format. | |
| 500, 501, 502 to 504, timeouts | Server or gateway trouble | Retry with backoff. |
Retries and backoff
Retry only what can succeed on a second try: timeouts, connection errors and 5xx answers. Never retry 400, 401, 403 or 406 without a change. Wait longer each time (for example 2, 4, 8, 16, 32 seconds plus a little random jitter) and stop after five tries. Since a rate-limit hit bans the IP for good, it is better to slow down than to retry fast.
import random, time, requests
RETRY = {500, 502, 503, 504}
def call_with_retry(fn, tries=5):
for n in range(tries):
try:
return fn()
except requests.HTTPError as e:
if e.response.status_code not in RETRY:
raise # 400/401/403/406: fix, do not retry
except (requests.Timeout, requests.ConnectionError):
pass
time.sleep(2 ** (n + 1) + random.random())
raise RuntimeError("REDCap call failed after retries")
Timeouts on large exports
Set a client timeout that matches the batch size, and shrink the batch rather than raise the timeout without end. The University of Oregon reports 504 gateway timeouts on large uploads, and redcapAPI warns that exporting a project with all files "may prevent it from completing". Smaller batches by record id, or by date window, are the fix.
Idempotent imports
An import is safe to repeat when the same input always gives the same result. REDCap imports are upserts by record id, event and instance, so sending the same rows twice writes the same values. To keep it that way:
- Use your own stable record ids, not
forceAutoNumber. With auto-numbering, a retried batch can create a second record. - Send every field you own, every time, with
overwriteBehavior=normal. Useoverwriteonly when you mean to blank fields, since it erases stored values you leave empty. REDCapR's writer blanks cells by default (overwrite_with_blanks = TRUE), so set it on purpose. - Ask for
returnContent=idsand compare the list with what you sent.
Partial failures
One bad value can fail a whole batch. When a batch fails with 400, split it in half and retry each half until you isolate the bad rows. Send the good rows, park the bad ones in a review queue with the error text, and alert the data manager. REDCapR's continue_on_error flag shows the same choice: stop at the first failed batch (its default) or carry on.
Reconciliation
After each run, compare three counts: rows the source sent, ids REDCap returned, and rows a follow-up export finds. Once a week, export the whole project and compare record by record with the target. The log export shows who changed what and when, which helps when numbers differ.
Monitoring
Alert on: any 401 or 403, any run that writes zero rows when the source had changes, a run that takes twice as long as usual, a change in the data dictionary (export it daily and compare), and a change in the REDCap version (the version method). Keep the alert text free of patient data. REDCapR warns that verbose output "might contain sensitive information (e.g. PHI)".
Token storage and rotation
Illinois advises never sharing a token, never testing it in a browser, keeping it out of plain text in scripts, and regenerating it every 90 days. Health Research BC advises verifying the server's SSL certificate on every call. Keep tokens in a secrets manager. Plan rotation as a routine: get the new token, update the secret, run a test export, then ask the admin to delete the old one.
How do you connect REDCap with an EHR, a warehouse and other EDCs?
Many studies run REDCap next to an EHR, a data warehouse and sometimes a commercial EDC such as Medidata Rave or Veeva Vault. Each pair of systems can be wired directly, but with four or five systems that becomes many fragile links. A hub keeps each system to one link. The design below is our engineering practice.
The hub pattern
| Hub part | Job |
|---|---|
| Connectors | One per system: REDCap API, EHR FHIR, warehouse loader, EDC API. Each knows its own limits and retries. |
| ID map | One table that links a study subject id to the REDCap record id, the EHR MRN, the EDC subject id and the site. |
| Field map | The mapping from step 3, versioned, one per project. |
| Queue | Holds each batch until it is written and checked, so a retry never skips data. |
| Audit log | What moved, when, from where, and the ids written. |
EHR and REDCap
For EHR data into a study, use CDIS where the institution has it. The hub then reads the study data from REDCap through the API like any other source. If CDIS is not enabled, a feed from the EHR's own interfaces is a separate build with its own approvals on the EHR side.
Warehouse
Load REDCap into the warehouse in its own shape first (one table per form, keyed by record, event and instance), then reshape. Keep the raw export for each run so you can replay it.
Other EDCs
Sponsors often run their own EDC while the site keeps REDCap. The hub maps REDCap fields to the EDC's forms and pushes them through that EDC's API. See our guides to the Medidata Rave EDC API and the Veeva Vault API for the other side.
Several REDCap projects or instances
Each project needs its own token, and each install can run its own version. A multi-site study can live in one project with Data Access Groups, so each site sees only its own records. Or each site can run its own project on its own install, and the hub merges them. Pick one project with DAGs when one institution can host every site. Pick separate projects when each site must keep data on its own server. Check each install's version on every run, since one upgrade can change behavior.
ID matching
Match people on a study id the hub assigns, stored in each system. Do not match on name and birth date alone, since typing differences create false matches and missed matches. Send any automatic match on weaker keys to a person to confirm before data moves. CDIS itself keys on the MRN the user enters.
What is not possible with a REDCap integration?
- No developer license and no own install for a vendor. A for-profit company cannot hold a license or self-host. The usual workaround is a customer institution's install, or REDCap Cloud, a separate company, for industry trials.
- No outside IT support for the system. "IT companies, and other third parties are NOT allowed to help with installation, maintenance, or support." Your build talks to REDCap through the API or a module the institution approves, and the institution's own staff run the system.
- No codebase access. Third parties "cannot access the REDCap codebase for any reason".
- No write back to the EHR through CDIS. Vanderbilt describes CDIS as pulling selected EHR data into REDCap. Writing into the EHR needs the EHR's own interfaces.
- No data out through DDP. DDP brings data in only.
- No Data Entry Trigger on imports. It fires only on "normal data entry on surveys and data entry forms".
- No bulk file export in one call. File export works one record at a time.
- No deleting arms or events in production. Those methods work only in development status.
- No guarantee one build works on every install. "Building an interface with a single system doesn't guarantee it would be compatible with all branches/versions of REDCap."
- No external modules in the REDCap Mobile App, as Yale documents for its installs.
What are the REDCap API limits, cost and timelines?
Limits
| Limit | What is published |
|---|---|
| Rate limit | REDCap limits web requests per minute per IP. Past the limit, "the IP address of that user is permanently banned". The value is set locally in the Control Center. No separate number for /api/ calls is published. |
| Size and time | No published size cap for API calls. Large exports and uploads can time out at the gateway. |
| Scope of a token | One user, one project. |
| Production projects | The API Playground lists fewer methods in production. Arm and event deletes work only in development. |
| Files | One record per file call. |
| Token hygiene | Illinois asks users to regenerate tokens every 90 days. |
| Cloned projects | Tokens are not created when a project is cloned. |
| CDIS data | Only the data groups in section 7. |
| Versions | Each install runs its own version. Vanderbilt's own install was on 17.6.2 when we checked. |
Cost
- License: "there is no cost or fee of any kind" for non-profits.
- Hosting at Vanderbilt: redcap.vumc.org is available "for a monthly fee" to US groups aligned with its mission. The price is not on the FAQ page.
- REDCap Cloud: fee-based hosting from a separate company. Its prices are not on Vanderbilt's pages.
- Staff time: Vanderbilt suggests 0.25 FTE for a system administrator in the first two months, then 0.1 FTE, plus 0.5 FTE for non-technical user support.
- EHR side: no fee for the REDCap app in Epic or Cerner is published on any page we read.
- Custom external modules: Yale notes that "EMs may sometimes incur costs" and runs paid development.
Ask your EHR team whether the REDCap client app carries a fee, and ask your REDCap admin what internal charges apply to API or module review.
Timelines
| Step | Published time |
|---|---|
| License review | Up to six weeks. |
| Community accounts after the license | Up to two more weeks. Vanderbilt says to plan for about a month. |
| Install and launch | "Entirely up to" the institution's technical team. |
| Custom module review at Yale | Set-up and testing "may take several weeks". |
| CDIS set-up with the EHR | Not published. |
| API token approval | Not published. Ask your REDCap admin. |
Which REDCap quirks should you know?
Each comes from Vanderbilt, an institution's own documents, or the client libraries' docs.
DDP is now Clinical Data Pull, for EHRs
The CDIS page says CDP was "formerly called Dynamic Data Pull (DDP)". The technical overview still describes DDP as the general route that needs host-built web services. Ask which one your admin means.
The API help is behind a login
Each install has its own API documentation page, and it shows a login screen to visitors. Ask your admin for the method list for your version.
Production projects hide methods
The API Playground lists fewer methods once a project is in production. Build against a development copy.
"Execute Request" changes real data
The Playground button runs the call on the project.
Cloning a project drops the tokens
A cloned test project needs new tokens.
The example ZIP is not official
The API example files "are not officially sanctioned REDCap files" and can change between versions.
The rate limit bans for good
Hitting the per-IP limit on web pages gets the IP "permanently banned". Space out batch jobs.
Imports do not fire the Data Entry Trigger
It runs only on "normal data entry on surveys and data entry forms". A sync that relies on it misses records loaded by API import or the Data Import Tool.
Filtering by form drops the record id
REDCap does not add record_id unless you ask for it.
Asking for record_id adds three columns
You get redcap_event_name, redcap_repeat_instrument and redcap_repeat_instance too.
DAG export depends on who holds the token
exportDataAccessGroups only works when the token's user is not in a DAG.
Overwrite mode blanks fields
overwriteBehavior=overwrite erases stored values you send empty, and REDCapR's writer blanks by default.
Only three date formats import
YMD, MDY or DMY.
FHIR version history
In 2021 the team wrote that CDIS supported DSTU2, with R4 resources such as encounters and appointments planned. The CDIS page now lists encounters and appointments.
What blocks a REDCap integration, and how do you clear each blocker?
| Blocker | Why it happens | How to clear it | Source |
|---|---|---|---|
| The institution has not approved API use | Tokens need admin approval and, on first request, an API agreement | Ask the admin early. Send the scope from step 1 with the request. | |
| A vendor wants to help run REDCap | The license bars third parties from install, maintenance and support | Keep your work outside REDCap: API clients, the institution-approved modules, and the other systems. The institution's staff run REDCap. | |
| IP banned by the rate limit | The limit is set locally and a hit is permanent | Ask the admin for the limit. Batch, pause between calls, and back off on errors. | |
| Large exports time out | Gateways cut long requests | Batch by record id or date window. Skip files in bulk exports. | |
| Different versions at each institution | Each install upgrades on its own schedule | Read the version on each run. Test against each install. | |
| The Data Entry Trigger gives no data guarantee | It is a notice, its fields vary by version, and imports do not fire it | Use it only to wake a job that exports by API. Keep a polling job with dateRangeBegin. | |
| Imports do not fire the trigger | By design | Downstream systems poll, or the importer tells them directly. | |
| Field validation fails | Values break the data dictionary's type or range | Validate against the exported metadata before sending. Drop calculated fields. | |
| PHI and IRB rules | Identified data needs IRB approval and the right export rights | Ask the PI which fields can leave. Use de-identified exports where you can. | |
| 21 CFR Part 11 | Compliance belongs to the environment and the process, not the software | Use the institution's validated instance if it has one (UW runs one), or REDCap Cloud (WashU uses it). Ask whether external modules are allowed on it. | |
| Security review of a custom module | Institutions review modules before install | Plan weeks for review. Keep the module small. | |
| CDIS not enabled | It needs the admin and Health IT | Ask both teams. Without CDIS, an EHR feed is a separate build. |
A word on Part 11
Vanderbilt says "no software alone is truly compliant with any standard". The University of Washington runs a validated REDCap Part 11 instance and states that "using REDCap alone does not automatically make a project 21 CFR Part 11 compliant". WashU uses REDCap Cloud, from nPhase, Inc., for Part 11 regulated research. Yale restricts external modules on its Part 11 validated servers. So for a regulated trial, ask which instance the study runs on and what that instance allows before you design.
How do you handle REDCap project changes, moves and multi-site studies?
Changes in production (Draft Mode)
Once a project is in production, forms cannot be edited directly. The data manager enters Draft Mode, makes changes and submits them. "If the changes will delete or invalidate existing data, then the changes must be reviewed by a REDCap administrator." Each install chooses how strict this is, from "Never (always require an admin to approve changes)" to more lenient settings. All changes in one submission are approved or rejected together. Draft Preview Mode lets users test drafted changes with throwaway data before they submit, though it does not work on survey pages.
What this means for an integration:
- Variable names never change in production. Your field map stays valid unless fields are added or deleted.
- A changed label can change the meaning of data. UW-Madison's example is a field that changed from days to weeks. Watch the metadata for label and choice changes as well as new fields.
- Deleting a field with data loses that data. Ask the data manager to tell you before any delete.
Mid-study instrument changes
Export the data dictionary every day and compare it with yesterday's. On any change, pause writes, update the field map, test in development, and resume. UW-Madison suggests adding a new field and hiding the old one with @HIDDEN, rather than changing a field that has data. That keeps old values readable for your feed. BIDMC advises backing up with a full export before major changes. Your weekly full export can serve as that backup.
Project migration
A project can move between servers as CDISC ODM XML. The University of Oregon guide uses Other Functionality, then "Download metadata & data (XML)", then New Project and upload. Through the API, redcapAPI's exportProjectXml does the same and can include records. Known issues: some 9.4.2 exports miss the closing </odm> tag, and big uploads can hit 504 timeouts. After a move, every token must be issued again, since the project is new. Run a full count check against the old project before you switch your feed.
Multi-site studies
Data Access Groups let one project serve many sites, with each site's users seeing only their own records. If the integration must see every site, give its token to a user outside any DAG. Then exportDataAccessGroups=true adds the site column. If sites run separate installs, treat each one as its own source in the hub (section 10).
De-identified exports
The Data Export Tool can "remove free-form text fields, remove dates, perform date shifting, and remove fields tagged as identifiers". User rights can force these rules on a user's exports. For an analytics feed, ask for a service user with de-identified export rights, and make sure identifier fields are flagged in the data dictionary. Through the API, check what your user's rights return before you trust that a field is absent.
What should you check before you sign a REDCap integration?
Security and compliance
Vanderbilt says "no software alone is truly compliant with any standard. It is the environment into which software is installed that can be called compliant." It does not fill in vendor security forms or BAAs for partner sites. So the institution's own team answers your security questions about its install.
Testing
Test on a development project, never in production. Plan for version differences between institutions. At Yale, custom modules go through a security review and a Security Planning Assessment before install.
Questions to ask your REDCap admin and EHR team
- Which REDCap version do you run, and when is the next upgrade?
- Who approves API tokens, and is there an API agreement to sign?
- Can the integration run under its own service user?
- What is the local rate limit in the Control Center?
- How are production changes approved here?
- Is CDIS enabled, and with which EHR? Which data groups are switched on?
- What IRB and key personnel checks apply before CDIS works on a project?
- Can you give us a development project and a test token?
- What review does a custom external module need, and how long does it take?
- Does the EHR team charge for the REDCap client app?
- Is this study on a Part 11 validated instance, and what does it allow?
- Under your license, which parts of our work need your staff to carry out?
What is the next step for a REDCap integration?
A REDCap integration starts with the institution that runs REDCap. Bring its admin in early, and plan the build around the API, CDIS or a module they can approve. For help with the EHR side of the link, see our EHR integration services.
Ready to scale?
Talk to our healthcare engineering team about building, integrating, and shipping faster.
Frequently Asked Questions
Does REDCap have an API?
How do I get a REDCap API token?
What formats does the REDCap API return?
How do I export only changed REDCap records?
What is REDCap CDIS?
What is the difference between Clinical Data Pull and Clinical Data Mart?
Does REDCap support FHIR and work with Epic?
Can a software company get its own REDCap license?
Is REDCap free?
Can I use the REDCap API with Python?
Which R packages work with the REDCap API?
What is a REDCap Data Entry Trigger?
How do I avoid duplicate records when an import is retried?
Is REDCap 21 CFR Part 11 compliant?


