Prolific recruitment

Use Prolific to recruit participants for a hosted human survey. This workflow requires an Expected Parrot account and recruitment funding. You do not need to run a simulation first. There are two linked objects: the human survey contains the questionnaire and collected answers, while the Prolific study defines recruitment, participant numbers, and payment. The examples keep both human_survey_uuid and study_id because recruitment operations refer to that pair. If you already have participants and will distribute the survey link yourself, use Human studies directly.

Prepare and preview the survey

Construct and pilot your survey with Human surveys. Save the reviewed EDSL survey as survey.ep and retain the UUID returned by .humanize(). The examples below assume that hosted survey already exists:

from edsl import Coop, Survey

coop = Coop()
survey = Survey.load("survey.ep")
human_survey_uuid = "YOUR_HUMAN_SURVEY_UUID"

Replace the UUID with the actual returned identifier. Check the respondent experience and completion flow before recruitment.

Participant limit

Check the account configuration that will apply to a new study:

settings = coop.get_prolific_study_settings()

key_source identifies Expected Parrot’s account (ep) or your own configured Prolific key (user_key). Inspect charged_in_credits, participant_limit_applies, and participant_limit before selecting the sample size. Billing and limits depend on this configuration; do not assume a fixed account-wide allowance.

Estimate and create a draft

The following example requests ten participants, estimates five minutes per participant, and offers 100 cents each. Replace these values with the pilot-based duration, payment, and sample size for your study. Estimation and draft creation contact the service but do not publish the study.

cost = coop.calculate_prolific_study_cost(
    participant_payment_cents=100,
    num_participants=10,
    estimated_completion_time_minutes=5,
)

Review the estimate and account settings before creating the draft:

study = coop.create_prolific_study(
    human_survey_uuid=human_survey_uuid,
    name="Workplace experience",
    description="A five-minute survey about work arrangements.",
    num_participants=10,
    estimated_completion_time_minutes=5,
    participant_payment_cents=100,
    approval_mode="manual",
)
study_id = study["study_id"]

The returned admin_url and preview_url let you review the draft. Use coop.list_prolific_filters() to discover supported screening filters; its returned object provides find() and create_study_filter() for constructing the filters argument. Select filters from the current catalog rather than copying historical IDs.

Check and publish

Check the deployed survey and funding before publishing:

check = coop.preflight_prolific_study(
    human_survey_uuid,
    study_id,
    expected_survey=survey,
    required_questions=survey.question_names,
)
if not check["ready"]:
    raise RuntimeError(check["blockers"])

A successful check does not reserve funds or test the full respondent experience. If the survey includes paid AI interviews or other AI work, include those costs in required_credits as well. Publishing starts recruitment and can incur charges. Run the following only when the instrument, sample, payment, and budget are ready for launch:

published = coop.publish_prolific_study(
    human_survey_uuid,
    study_id,
    expected_survey=survey,
    required_questions=survey.question_names,
)

Publishing repeats the preflight check. Inspect the returned status rather than treating a successful request as completed data collection.

Monitor and retrieve responses

status = coop.get_prolific_study(human_survey_uuid, study_id)
responses = coop.get_prolific_study_responses(human_survey_uuid, study_id)

Inspect the returned data type and response count before applying Results methods. Retain the study identifier, participant identifiers, collection dates, and any exclusions in the analysis record.

Submission approval

approval_mode="automatic" approves a submission when the participant enters the completion code. "manual" requires you to review and manage submissions; Prolific’s own automatic-approval rules still apply. Choose the mode before publishing and monitor submissions through the study’s admin page. Use the study’s admin page to manage submissions and changes to recruitment. Check the current study state before making changes.

Manage an existing study from Python

coop.list_prolific_studies(human_survey_uuid) lists recruitment studies for a human survey. coop.update_prolific_study(human_survey_uuid, study_id, ...) updates supported settings; allowed changes depend on the study’s current state.

Action	Method
Pause recruitment	`coop.pause_prolific_study(human_survey_uuid, study_id)`
Resume recruitment	`coop.resume_prolific_study(human_survey_uuid, study_id)`
Stop recruitment	`coop.stop_prolific_study(human_survey_uuid, study_id)`
Approve a reviewed submission	`coop.approve_prolific_study_submission(human_survey_uuid, study_id, submission_id)`
Reject a reviewed submission	`coop.reject_prolific_study_submission(human_survey_uuid, study_id, submission_id, reason=reason_code, explanation=explanation)`
Delete a study	`coop.delete_prolific_study(human_survey_uuid, study_id)`

These methods change the live recruitment or submission state. Approval and rejection affect participant payment; use them for deliberate review decisions under Prolific’s applicable rules. The rejection reason must be a supported code, such as FAILED_INSTRUCTIONS or OTHER, and the explanation must contain at least 100 characters. Inspect get_prolific_study() before and after a change; the service can reject actions that are invalid for the current state.

Introduction

Setup and tutorials

EDSL objects

How-to guides

Research examples

Human research

Execution and costs

Saving and sharing

Research and teaching

Expected Parrot platform

Contributing

Prepare and preview the survey

Participant limit

Estimate and create a draft

Check and publish

Monitor and retrieve responses

Submission approval

Manage an existing study from Python

​Prepare and preview the survey

​Participant limit

​Estimate and create a draft

​Check and publish

​Monitor and retrieve responses

​Submission approval

​Manage an existing study from Python

Prepare and preview the survey

Participant limit

Estimate and create a draft

Check and publish

Monitor and retrieve responses

Submission approval

Manage an existing study from Python