General API Info
Supported Methods
Arms
Data Access Groups
Events
Field Names
Files
File Repository
Instruments
Logging
Metadata
Projects
Records
Repeating Instruments and Events
Reports
REDCap
Surveys
Users & User Privileges
User Roles
REDCap API Documentation
Method Name
Import Events
Description
This method allows you to import Events into a project or to update existing Events' attributes, such as the event name, days offset, etc. The unique event name of an Event cannot be changed because it is auto-generated by REDCap. Please note that the only way to update an existing Event is to provide the unique_event_name attribute, and if the unique_event_name attribute is missing for an Event being imported (when override=0), it will assume it to be a new Event that should be created. Notice: Because of the 'override' parameter's destructive nature, this method may only use override=1 for projects in Development status.
NOTE: This only works for longitudinal projects.
URL
Supported Request Method
Permissions Required
To use this method, you must have API Import/Update privileges *and* Project Design/Setup privileges in the project.
Parameters (case sensitive)
Required
token
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
The API token specific to your REDCap project and username (each token is unique to each user for each project). See the section on the left-hand menu for obtaining a token for a given project.
content
event
event
action
import
import
override
0 - false [default], 1 - true — You may use override=1 as a 'delete all + import' action in order to erase all existing Events in the project while importing new Events. If override=0, then you can only add new Events or modify existing ones.
0 - false [default], 1 - true — You may use override=1 as a 'delete all + import' action in order to erase all existing Events in the project while importing new Events. If override=0, then you can only add new Events or modify existing ones.
format
csv, json, xml [default]
csv, json, xml [default]
data
Contains the required attributes 'event_name' (referring to the name/label of the event) and 'arm_num' (referring to the arm number to which the event belongs - assumes '1' if project only contains one arm). In order to modify an existing event, you must provide the attribute 'unique_event_name' (referring to the auto-generated unique event name of the given event). If the project utilizes the Scheduling module, the you may optionally provide the following attributes, which must be numerical: day_offset, offset_min, offset_max. If the day_offset is not provided, then the events will be auto-numbered in the order in which they are provided in the API request.
Contains the required attributes 'event_name' (referring to the name/label of the event) and 'arm_num' (referring to the arm number to which the event belongs - assumes '1' if project only contains one arm). In order to modify an existing event, you must provide the attribute 'unique_event_name' (referring to the auto-generated unique event name of the given event). If the project utilizes the Scheduling module, the you may optionally provide the following attributes, which must be numerical: day_offset, offset_min, offset_max. If the day_offset is not provided, then the events will be auto-numbered in the order in which they are provided in the API request.
JSON Example:
[{"event_name":"Baseline","arm_num":"1","day_offset":"1","offset_min":"0",
"offset_max":"0","unique_event_name":"baseline_arm_1"},
{"event_name":"Visit 1","arm_num":"1","day_offset":"2","offset_min":"0",
"offset_max":"0","unique_event_name":"visit_1_arm_1"},
{"event_name":"Visit 2","arm_num":"1","day_offset":"3","offset_min":"0",
"offset_max":"0","unique_event_name":"visit_2_arm_1"}]CSV Example:
event_name,arm_num
"Baseline",1
"Visit 1",1
"Visit 2",1XML Example:
<?xml version="1.0" encoding="UTF-8" ?>
<events>
<item>
<event_name>Baseline</event_name>
<arm_num>1</arm_num>
</item>
<item>
<event_name>Visit 1</event_name>
<arm_num>1</arm_num>
</item>
<item>
<event_name>Visit 2</event_name>
<arm_num>1</arm_num>
</item>
</events>
Optional
ReturnsreturnFormat
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
NOTE: Does not apply when importing as a background process (i.e., backgroundProcess=true). When using a background process, success:true (upon success) or success:false (upon failure) will be returned in the appropriate format (csv, json, xml).
csv, json, xml - specifies the format of error messages. If you do not pass in this flag, it will select the default format for you passed based on the 'format' flag you passed in or if no format flag was passed in, it will default to 'xml'.
NOTE: Does not apply when importing as a background process (i.e., backgroundProcess=true). When using a background process, success:true (upon success) or success:false (upon failure) will be returned in the appropriate format (csv, json, xml).
Number of Events imported