Skip to content

Import Events

Import Events API

Article ID RC-API-20 — Import Events API
Domain API
Applies To Longitudinal REDCap projects only
Prerequisite RC-API-01 — REDCap API
Version 1.1
Last Updated 2026
Author See KB-SOURCE-ATTESTATION.md
Source REDCap API v16.1.3 official documentation examples
Related Topics RC-API-01 — REDCap API; RC-API-19 — Export Events API; RC-API-21 — Delete Events API

1. Overview

The Import Events API method creates or modifies events in a longitudinal REDCap project. Events are timepoints or phases within an arm. Each event has a name, label, arm assignment, and offset information.

The override parameter controls behavior: when set to 0, the method adds or modifies events without deleting others; when set to 1, all existing events are deleted and replaced with the events you provide.

To modify an existing event, provide its unique_event_name. If unique_event_name is missing from a record and override=0, REDCap treats it as a new event to create. The unique_event_name cannot be changed — it is auto-generated by REDCap and is permanent.

Important: Events exist only in longitudinal projects. This method will return an error if called on a classic (non-longitudinal) project.

Important: This method is only available for projects in Development status. It cannot be used on projects in Production or Analysis/Cleanup status.

2. Parameters

Parameter Required Description
token Required Your project API token. Requires API Import/Update privileges and Project Design/Setup privileges.
content Required Always 'event' for this method.
action Required Always 'import' for this method.
override Required 0 = add new events or modify existing ones without deleting others (default); 1 = delete all existing events and replace with the provided set.
format Optional Data format: 'csv', 'json', or 'xml'. Default is 'xml'.
data Required The event records to import. Each record must include event_name (the human-readable label) and arm_num (the arm the event belongs to; assumes 1 if the project has only one arm). To modify an existing event, you must also provide unique_event_name. The offset fields day_offset, offset_min, and offset_max are optional and must be numeric; if day_offset is omitted, events are auto-numbered in the order provided. The unique_event_name of an existing event cannot be changed — it is auto-generated by REDCap.
returnFormat Optional Format for error messages: 'csv', 'json', or 'xml'. Defaults to whatever format is set to. If neither is provided, defaults to 'xml'. Not applicable when using background processing.

3. Request Examples

3.1 Python

from config import config
import requests, json

record = {
    'event_name': 'Event 1',
    'arm_num': 1,
    'day_offset': 0,
    'offset_min': 0,
    'offset_max': 0,
    'unique_event_name': 'event_1_arm_1'
}

data = json.dumps([record])

fields = {
    'token': config['api_token'],
    'content': 'event',
    'action': 'import',
    'format': 'json',
    'override': 0,
    'data': data,
}

r = requests.post(config['api_url'],data=fields)
print('HTTP Status: ' + str(r.status_code))
print(r.text)

3.2 R

source('config.R')
library(RCurl)
library(jsonlite)

record <- c(
    event_name='Event 1',
    arm_num=1,
    day_offset=0,
    offset_min=0,
    offset_max=0,
    unique_event_name='event_1_arm_1'
)

data <- toJSON(list(as.list(record)), auto_unbox=TRUE)

result <- postForm(
    api_url,
    token=api_token,
    content='event',
    action='import',
    format='json',
    override=0,
    data=data
)
print(result)

3.3 cURL

. ./config

DATA="token=$API_TOKEN&content=event&action=import&override=0&format=json&data=[{\"event_name\":\"Event%201\",\"arm_num\":\"1\",\"day_offset\":\"0\",\"offset_min\":\"0\",\"offset_max\":\"0\",\"unique_event_name\":\"event_1_arm_1\"}]"

$CURL -H "Content-Type: application/x-www-form-urlencoded" \
      -H "Accept: application/json" \
      -X POST \
      -d $DATA \
      $API_URL

3.4 PHP

<?php

include 'config.php';

$data = array(
    array(
        'event_name'        => 'Event XX',
        'arm_num'           => '1',
        'day_offset'        => '0',
        'offset_min'        => '0',
        'offset_max'        => '0',
        'unique_event_name' => 'event_xx_arm_1'
    ),
    array(
        'event_name'        => 'Event YY',
        'arm_num'           => '2',
        'day_offset'        => '0',
        'offset_min'        => '0',
        'offset_max'        => '0',
        'unique_event_name' => 'event_yy_arm_2'
    ),
);

$data = json_encode($data);

$fields = array(
    'token'    => $GLOBALS['api_token'],
    'content'  => 'event',
    'action'   => 'import',
    'format'   => 'json',
    'override' => 1,
    'data'     => $data,
);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $GLOBALS['api_url']);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields, '', '&'));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); // Set to TRUE for production use
curl_setopt($ch, CURLOPT_VERBOSE, 0);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($ch, CURLOPT_AUTOREFERER, true);
curl_setopt($ch, CURLOPT_MAXREDIRS, 10);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_FRESH_CONNECT, 1);

$output = curl_exec($ch);
print $output;

Note: In PHP examples, CURLOPT_SSL_VERIFYPEER is shown as FALSE for compatibility. Set it to TRUE in production. See RC-API-01 — REDCap API — Section 3.5 for why SSL certificate validation matters.

4. Response

On success, the method returns the number of events imported as a plain integer (not a JSON object). The HTTP status code will be 200.

Example response:

3

5. Common Questions

Q: What is the unique_event_name and how does it differ from event_name?

A: The event_name is the human-readable label (e.g., "Baseline Visit"). The unique_event_name is the system identifier used in data exports and API calls (e.g., event_1_arm_1 or baseline_visit_arm_1). The unique_event_name must be unique and typically follows the pattern [event_label]_arm_[arm_num].

Q: What do the offset fields represent?

A: day_offset is the expected number of days after enrollment for the event. offset_min and offset_max define the acceptable window. For example, a visit expected at day 7 with min/max of ±3 days is acceptable from day 4 to day 10. These are used for visit compliance tracking.

Q: Can I use this method on a classic project?

A: No. Events are a longitudinal-only feature. This method will fail on classic projects.

Q: My project is in Production. Can I still use Import Events?

A: No. Import Events is only available for projects in Development status. If you need to add or modify events on a Production project, you must first move it back to Development status, make your changes, and then return it to Production. Be aware that this process requires careful coordination to avoid disrupting active data collection.

Q: Do I need any special permissions beyond API access?

A: Yes. You need both API Import/Update privileges and Project Design/Setup privileges in the project. API Export rights alone are not sufficient.

Q: What happens if I specify an arm_num that does not exist?

A: The API will return an error. You must specify arm_num values that correspond to existing arms in the project. Use Export Arms (RC-API-16 — Export Arms API) to discover valid arm numbers.

6. Common Mistakes & Gotchas

Calling Import Events on a classic project. Events are a longitudinal-only feature. This method will fail on classic projects. Always verify your project is longitudinal before calling this method.

Calling Import Events on a Production project. This method only works when the project is in Development status. Calling it on a Production project will return an error. Move the project back to Development before making structural event changes.

Forgetting to JSON-encode the data parameter. The data parameter must be a valid JSON array. Use json.dumps() in Python, toJSON() in R, or json_encode() in PHP to properly format it.

Using event_name when you should use unique_event_name. The event_name is the label; the unique_event_name is the identifier. In other API calls, always use unique_event_name.

Using override=1 when you only want to add a single event. The override=1 flag deletes all existing events. If you only want to add or modify one event, use override=0 instead.