Plugins, Hooks, & External Modules
Developer methods for
Plugins, Hooks, & External Modules
Hook functions
REDCap Developer Tools:
Documentation for Plugins, Hooks, & External Modules
REDCap Version 14.9.1
REDCap::getParticipantList
(REDCap >= 6.4.0)
REDCap::getParticipantList
— Returns the list of all participants for a specific survey instrument (and for a specific event, if a longitudinal project)
Description
mixed REDCap::getParticipantList ( string $instrument [, int $event_id [, string $return_format = 'array' ]] )
Returns the list of participants for a specific survey instrument (and for a specific event, if a longitudinal project). This method assumes the instrument has already been enabled as a survey in the project.
Parameters
instrument
The name of the data collection instrument (i.e., the unique name, not the instrument label) to which this survey corresponds. This corresponds to the value of Column B in the Data Dictionary.
The name of the data collection instrument (i.e., the unique name, not the instrument label) to which this survey corresponds. This corresponds to the value of Column B in the Data Dictionary.
event_id
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
(longitudinal projects only) The event ID number that corresponds to a defined event in a longitudinal project. For classic projects, the event_id is not explicitly required, and thus it will be supplied automatically since there will only ever be one event_id for the project.
return_format
The format in which the list should be returned. Valid options: 'array', 'csv', 'json', and 'xml'. By default, 'array' is used.
The format in which the list should be returned. Valid options: 'array', 'csv', 'json', and 'xml'. By default, 'array' is used.
Return Values
Returns the list of all participants for the specified survey instrument [and event] in the desired format. The following fields are returned: email, email_occurrence, identifier, record, invitation_sent_status, invitation_send_time, response_status, survey_access_code, survey_link. The attribute "email_occurrence" represents the current count that the email address has appeared in the list (because emails can be used more than once), thus email + email_occurrence represent a unique value pair. "invitation_sent_status" is "0" if an invitation has not yet been sent to the participant, and is "1" if it has. "invitation_send_time" is the date/time in which the next invitation will be sent, and is blank if there is no invitation that is scheduled to be sent. "response_status" represents whether the participant has responded to the survey, in which its value is 0, 1, or 2 for "No response", "Partial", or "Completed", respectively. Note: If an incorrect event_id or instrument name is used or if the instrument has not been enabled as a survey, then NULL will be returned.
Restrictions
This method can ONLY be used in a project context (i.e. when "pid" parameter is in the query string of the plugin URL) or else a fatal error is produced.
Examples
Example #1:
This example illustrates how to obtain the participant list as an array for a classic (non-longitudinal) project.
// The unique instrument name for the survey $instrument = 'participant_info_survey'; // Get the participant list for this instrument $participant_list_array = REDCap::getParticipantList($instrument);
Example #2:
This example illustrates how to obtain the participant list in JSON format for a classic (non-longitudinal) project.
// The unique instrument name for the survey $instrument = 'participant_info_survey'; // Get the participant list for this instrument $participant_list_json = REDCap::getParticipantList($instrument, NULL, 'json');
Example #3:
This example demonstrates how to obtain the participant list in CSV format for a specific survey and event in a longitudinal project.
// The unique instrument name for the survey and the event_id for the event $instrument = 'participant_info_survey'; $event_id = 339; // Get the participant list for this instrument-event $participant_list_csv = REDCap::getParticipantList($instrument, $event_id, 'csv');
REDCap 14.9.1 - © 2024 Vanderbilt University