Surveys

REDCap API methods for Project surveys

Surveys (Base)

Responsible for all API methods under 'Surveys' in the API Playground

Source code in redcap/methods/surveys.py

class Surveys(Base):
    """Responsible for all API methods under 'Surveys' in the API Playground"""

    def export_survey_participant_list(
        self,
        instrument: str,
        format_type: Literal["json", "csv", "xml", "df"] = "json",
        event: Optional[str] = None,
        df_kwargs: Optional[Dict[str, Any]] = None,
    ):
        """
        Export the Survey Participant List

        Note:
            The passed instrument must be set up as a survey instrument.

        Args:
            instrument:
                Name of instrument as seen in the Data Dictionary (metadata).
            format_type:
                Format of returned data
            event:
                Unique event name, only used in longitudinal projects
            df_kwargs:
                Passed to `pandas.read_csv` to control construction of
                returned DataFrame. By default, nothing

        Returns:
            Union[List[Dict[str, Any]], str, pandas.DataFrame]:
                List of survey participants,
                along with other useful
                metadata such as the record, response status, etc.

        Examples:
            >>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
            [{'email': '',
            ...
            'survey_access_code': ...},
            {'email': '',
            ...
            'survey_access_code': ...}]
        """
        payload = self._initialize_payload(
            content="participantList", format_type=format_type
        )
        payload["instrument"] = instrument
        if event:
            payload["event"] = event

        return_type = self._lookup_return_type(format_type, request_type="export")
        response = cast(Union[Json, str], self._call_api(payload, return_type))

        return self._return_data(
            response=response,
            content="participantList",
            format_type=format_type,
            df_kwargs=df_kwargs,
        )

def_field: str inherited property readonly

The 'record_id' field equivalent for a project

field_names: List[str] inherited property readonly

Project field names

!!! note These are survey field names, not export field names

forms: List[str] inherited property readonly

Project form names

is_longitudinal: bool inherited property readonly

Whether or not this project is longitudinal

metadata: Json inherited property readonly

Project metadata in JSON format

token: str inherited property readonly

API token to a project

url: str inherited property readonly

API URL to a REDCap server

export_survey_participant_list(self, instrument, format_type='json', event=None, df_kwargs=None)

Export the Survey Participant List

!!! note The passed instrument must be set up as a survey instrument.

Parameters:

Name	Type	Description	Default
instrument	str	Name of instrument as seen in the Data Dictionary (metadata).	required
format_type	Literal['json', 'csv', 'xml', 'df']	Format of returned data	'json'
event	Optional[str]	Unique event name, only used in longitudinal projects	None
df_kwargs	Optional[Dict[str, Any]]	Passed to pandas.read_csv to control construction of returned DataFrame. By default, nothing	None

Returns:

Type	Description
Union[List[Dict[str, Any]], str, pandas.DataFrame]	List of survey participants, along with other useful metadata such as the record, response status, etc.

Examples:

>>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
[{'email': '',
...
'survey_access_code': ...},
{'email': '',
...
'survey_access_code': ...}]

Source code in redcap/methods/surveys.py

def export_survey_participant_list(
    self,
    instrument: str,
    format_type: Literal["json", "csv", "xml", "df"] = "json",
    event: Optional[str] = None,
    df_kwargs: Optional[Dict[str, Any]] = None,
):
    """
    Export the Survey Participant List

    Note:
        The passed instrument must be set up as a survey instrument.

    Args:
        instrument:
            Name of instrument as seen in the Data Dictionary (metadata).
        format_type:
            Format of returned data
        event:
            Unique event name, only used in longitudinal projects
        df_kwargs:
            Passed to `pandas.read_csv` to control construction of
            returned DataFrame. By default, nothing

    Returns:
        Union[List[Dict[str, Any]], str, pandas.DataFrame]:
            List of survey participants,
            along with other useful
            metadata such as the record, response status, etc.

    Examples:
        >>> proj.export_survey_participant_list(instrument="form_1", event="event_1_arm_1")
        [{'email': '',
        ...
        'survey_access_code': ...},
        {'email': '',
        ...
        'survey_access_code': ...}]
    """
    payload = self._initialize_payload(
        content="participantList", format_type=format_type
    )
    payload["instrument"] = instrument
    if event:
        payload["event"] = event

    return_type = self._lookup_return_type(format_type, request_type="export")
    response = cast(Union[Json, str], self._call_api(payload, return_type))

    return self._return_data(
        response=response,
        content="participantList",
        format_type=format_type,
        df_kwargs=df_kwargs,
    )