API ReferenceStudies

The study object

View as MarkdownOpen in Claude

Important Attributes

status

  • The status of a study can be of the following:
    • UNPUBLISHED- When a study is created, it is in a draft format.
    • PUBLISHING- Study publish has been triggered and is being processed.
    • ACTIVE- Study is published to participants.
    • SCHEDULED- Study is scheduled to be published at a specific date. Study is ‘ACTIVE’ when published.
    • PAUSED- Study is paused, participants are not shown the study and can not make submissions.
    • AWAITING REVIEW- All participants submissions are completed and not all have been reviewed yet.
    • COMPLETED- You have approved all participant submissions required for your study. If you have rejected one or more submissions, the study goes back to ‘AWAITING REVIEW’ until the number of accepted submissions has been reached.

external_study_url (required)

  • The external study URL of your study that you want participants to be direct to. The URL can be customized to add information to match participants in your survey. You can add query parameters with the following placeholders.

    • {{%PROLIFIC_PID%}}-> Participant Id
    • {{%STUDY_ID%}}-> This study Id
    • {{%SESSION_ID%}}-> The session Id

  • For example, you can define external_study_url to be https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}.

  • When participants access your study, they start a submission with their unique ID, allowing you to match their responses. You can approve or reject their submission, pay a bonus, or send a message against the unique ID.

completion_codes (required)

  • Completion codes verify that participants have completed your study as intended while automatically triggering actions based on their responses.

  • A completion code is a required field consisting of a random string of letters and numbers that participants receive when they complete your study. These codes serve two main purposes:

    1. Confirms submission and verifies that participants finished your study.
    2. Triggers automated actions based on the answer or the path of answers the participant selected. This saves you from having to manually process each submission

When participants finish your study, redirect them to:

$https://app.prolific.com/submissions/complete?cc={code}$

Setting up completion codes

Multiple codes: You can create as many codes as needed for your study and assign any number of automated actions to trigger when a submission is completed with that code - except when using a custom screening action, which is limited to a single code.

Automated actions

The actions field defines what happens automatically when a participant completes your study with their specific completion code. These are automated tasks that run when a participant submits the code.The list of automated actions are as follows:

  • Approve the submission- Payment is processed immediately
  • Hold for review- Submission waits for manual approval
  • Request return- Ask the participant to return their study (with explanation)
  • Manage participant groups- Add or remove participants to specific groups
  • Custom screening with fixed reward- Screen out participants based on your custom questions & pay them a fixed screened out reward, different from the study reward.
  • Pay a dynamic amount- Allows you to pay different amounts to participants based on their performance in your study.

filters (required)

  • Filters allow you to define participant criteria such as age, gender, and country. Learn how to set them under Requirements.

  • Related guide: Setting up a study on Prolific

Correct a published study if the estimated time is too high

  • If you estimated the time as too high and overpaid participants, you can ask the participants to return their studies voluntarily. They will not get paid, however, you should pay them the amount they have spent on your study manually.
    • First, stop your study using the STOP transition action.
    • Message participants to RETURN their submissions voluntarily. Many will do so, but you should pay them for their participation time via the web application or the Bonus API.
    • You can contact our support team for further help.
    • Duplicate the study with the corrected estimated time and reward using the clone endpoint or the web application.

rewards (required)

The reward is the total reward you pay a participant in cents (according to the currency of your account) when you approve a completed submission. We display the reward per hour in our web application by using the reward and estimated time.