> ## Documentation Index
> Fetch the complete documentation index at: https://docs.expectedparrot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Prolific recruitment

> Prepare a human survey, create a recruitment draft, and check it before launch.

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](https://docs.expectedparrot.com/en/latest/guides/human_studies.md) directly.

## Prepare and preview the survey

Construct and pilot your survey with [Human surveys](https://docs.expectedparrot.com/en/latest/humanize.md). Save the reviewed EDSL survey as `survey.ep` and retain the UUID returned by `.humanize()`. The examples below assume that hosted survey already exists:

```python theme={null}
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.

If the survey requires sign-in ([`survey.login_required`](https://docs.expectedparrot.com/en/latest/humanize_schema)), Prolific participants must sign in to an Expected Parrot account, or create one, before they can take it.

## Participant limit

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

```python theme={null}
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.

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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:

```python theme={null}
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

```python theme={null}
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](https://docs.expectedparrot.com/en/latest/results.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.