Transition a study's status

The transition action to execute on the study.

ISO 8601 datetime for when the study should be published. Required in the request when action is SCHEDULE_PUBLISH and the study does not already have a publish_at set.

Public name or title of the study

Internal name of the study, not shown to participants

Description of the study for the participants to read before starting the study

Supported HTML in description

The description field supports the following HTML tags for formatting participant instructions:

• <b> - bold
• <i> - italic
• <em> - emphasized text
• <strong> - strong importance
• <s> - strikethrough
• <u> - underline
• <h1> - heading level 1
• <h2> - heading level 2
• <ol> - ordered list
• <ul> - unordered list
• <li> - list item
• <p> - paragraph

Other HTML tags will be stripped or escaped. Please ensure that you only use supported tags for formatting to avoid rendering issues.

URL of the survey or experiment you want participant to access. You can pass URL search parameters to your survey or experiment

• Participant id {{%PROLIFIC_PID%}}
• Study id {{%STUDY_ID%}}
• Session id {{%SESSION_ID%}}

For example https://eggs-experriment.com?participant={{%PROLIFIC_PID%}}

Use 'question' if you will add a question in your survey or experiment asking the participant ID

Recommended Use 'url_parameters' if your survey or experiment can retrieve and store those parameters for your analysis.

Use 'not_required' if you don't need to record them.

How many participants are you looking to recruit.

Note: This field is optional when data_collection_method is set to AI_TASK_BUILDER_BATCH, as the total available places are automatically calculated from the batch configuration.

Estimated duration in minutes of the experiment or survey

Max time in minutes for a participant to finish the submission. Submissions are timed out if it takes longer.

If it is not provided the default value is set to the max value.

The min value is calculated as two minutes plus two times the estimated time plus two times the square root of the estimated time

How much are you going to pay the participants in cents. We use the currency of your account.

The ID of a filter set, from which filters for the study will be taken.

For more information, see Filter Sets.

Note, this cannot be used in combination with additional filters via the filters field.

The version of the filter set to be used.

If not provided, this will default to the latest available version at the time of applying the filter set.

Control the balance between speed of your studies and the naivety of the participants.

If not defined, by default Prolific calculates the best rate for most studies taking into account the filters and the total_available_places needed for this study.

Use 0 if your priority is speed. When this property is set to 0 all eligible participants will have access to your study at the same time, without any prioritization.

You can also set this at a workspace and project level.

Project ID. When you don't specify a project in your request, Prolific automatically uses your first created project as the default. For clarity, we recommend explicitly including the project ID in your requests.

Allow researchers to add further details about their content warning.

This field can be used to store extra information required for a system integration. For example, it could be some JSON, XML, an integer, or a string.

Examples could include:

• 123345 - An ID from your system, that helps with linkage when returning the study.
• { \"id\": \"45\", \"type\": \"finance\"} - Some JSON that you want to store.

The ID of the credential pool to associate with this study. Credential pools contain username/password pairs that are distributed to participants when they start the study.

When provided, participants will be assigned unique credentials from the pool. Each credential can only be used once and is tracked throughout the study lifecycle.

Note: The credential pool must:

• Exist and belong to the study's workspace
• Have available (unredeemed) credentials

See the Credentials endpoints for managing credential pools.

Indicates whether this study requires participants to use credentials. This field is automatically set to true when a credential_pool_id is provided, and false when the credential pool is removed.

Note: This field is automatically managed based on the credential_pool_id field and does not need to be set manually.

Optional. Specifies the data collection method for the study.

• AI_TASK_BUILDER_BATCH: Use AI Task Builder for data annotation tasks.
• AI_TASK_BUILDER_COLLECTION: Use AI Task Builder for data collection tasks.

Note: This field is mutually exclusive with external_study_url and access_details. If not provided, you must specify one of those fields instead.

The ID of the data collection batch or project from the Task Builder API.

Required when data_collection_method is set to AI_TASK_BUILDER_BATCH or AI_TASK_BUILDER_COLLECTION.

When set to true, any query parameters in the external study url will be signed with a JSON Web Token. The token will be added to the URL as a query parameter named prolific_token.

This feature is only available to certain workspaces.

The JWT payload

Header:

{
  "alg": "RS256",
  "kid": "<KEY_ID>",
  "typ": "JWT"
}

Where

• alg is always RS256.
• kid indicates the key ID that was used to secure the JWT.
• typ is always JWT.

Payload:

{
  "iss": "https://www.prolific.com",
  "iat": <CURRENT_TIME>,
  "exp": <CURRENT_TIME + 2 minutes>,
  "aud": "<EXTERNAL_STUDY_URL>",
  "sub": "<SESSION_ID>",
  "prolific":{
    "<QUERY_1>": "<VALUE_1>",
    "<QUERY_2>": "<VALUE_2>",
    ...
    "workspace_id": "<WORKSPACE_ID>",
    "organisation_id": "<ORGANISATION_ID>"
  }
}

<ORGANISATION_ID> appears only when the workspace is linked to an organisation; otherwise omit that key from prolific.

The prolific object maps each URL parameter from your external study URL template to the resolved value for that placeholder (for example participant, study, and session identifiers). Prolific always adds workspace_id (string). When the workspace is linked to an organisation, organisation_id (string) is also present.

For example (the sample below includes organisation_id; that key is omitted when the workspace has no linked organisation):

{
  "iss": "https://www.prolific.com",
  "iat": 1740496135,
  "exp": 1740496255,
  "aud": "https://x.com?STUDY_ID=1&...",
  "sub": "1234",
  "prolific":{
    "STUDY_ID": "abcd",
    "SESSION_ID": "1234",
    "PROLIFIC_PID": "xyz",
    "workspace_id": "507f1f77bcf86cd799439011",
    "organisation_id": "507f191e810c19729de860ea"
  }
}

Verify the payload

When you receive the JWT, you must verify the following:

• The JWT signature is authentic by verifying it with the public key from Prolific that correlates with the KID. The public keys can be retrieved from /.well-known/study/jwks.json.
• The JWT hasn't expired, by checking the exp claim.
• The aud claim is the correct domain for your tool.
• The prolific claim matches your expected payload as set in the external_study_url property. It always includes workspace_id. When the workspace is linked to an organisation, it also includes organisation_id (validate both against what your integration expects).

Study id. It is created by Prolific. Read only.

Status of the study. Read only.

To change the status you can use /api/v1/studies/{id}/transition/

Whether the study has all required fields completed for publishing. Does not check wallet balance or funding — only study-level field completeness.