API ReferenceStudies

Update a study

View as MarkdownOpen in Claude
You can update any field for a draft study. Once the study has been published only the following fields can be updated with some restrictions: - internal_name: Internal name of the study, not shown to participants - total_available_places: Only increasing is allowed. A completed study will become active again and resume recruiting of participants. For more information, check the [guide](https://researcher-help.prolific.com/en/articles/445201-how-do-i-increase-places-on-a-study) - access_details: Sending an access_detail will add a new task and increase overall study places by the number in the total_allocation field. Sending both access_details and total_available_places will increase places on existing URLs by the number specified on the access_detail. - submissions_config: This allows you to update the max_submissions_per_participant, max_concurrent_submissions, or auto_rejection_categories. Please note decreasing max_submissions_per_participant will not affect submissions that have already been created.

Authentication

Authorizationstring
The Prolific API uses API token to authenticate requests. You can create an API token directly from your settings. Your API token does not have an expiry date and carries full permission, so be sure to keep them secure. If your token is leaked, delete it and create a new one directly in the app. In your requests add `Authorization` header with the value `Token <your token>`.

Path Parameters

idstringRequired
Study id

Request

This endpoint expects an object.
namestringOptional
Public name or title of the study
internal_namestring or nullOptional
Internal name of the study, not shown to participants
descriptionstringOptional
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.
external_study_urlstringOptional
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%}}`
prolific_id_optionenumOptional

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.

Allowed values:
completion_codeslist of objectsOptional

Specify at least one completion code for your study. A participant will enter one of these codes when they complete your study.

Each code must be unique within a study.

You can specify as many actions as you like per code. However, some actions can’t be used together (e.g. AutomaticallyApprove and ManuallyReview).

total_available_placesdoubleOptional>=1

How many participants are you looking to recruit.

Note: This field is optional when data_collection_method is set to DC_TOOL or AI_TASK_BUILDER (AI Task Builder), as the total available places are automatically calculated from the batch configuration.

estimated_completion_timedoubleOptional>=1
Estimated duration in minutes of the experiment or survey
maximum_allowed_timedoubleOptional
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
rewarddoubleOptional
How much are you going to pay the participants in cents. We use the currency of your account.
device_compatibilitylist of enumsOptional
Add all devices that participants can use. You can include one or more options. An empty array indicates that all options are available.
Allowed values:
peripheral_requirementslist of enumsOptional
Add all requirements that participants have to meet. An empty array indicates that there are no extra peripheral requirements.
Allowed values:
filterslist of objects or nullOptional
Array of filters. Use empty array for "Everyone"
filter_set_idstring or nullOptional

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

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

filter_set_versioninteger or nullOptional
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.
projectstringOptional
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.
submissions_configobjectOptional

Advanced: This helps with faster data collection. Your survey system will need to handle providing a unique experience each time the participant takes the study.

Configuration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study.

study_labelslist of enumsOptional

This field allows you to tag studies with information about the type/topic of the study and the kind of work involved in completing it.

We plan to make this information available to participants for easier self-selection. At present these options are mutually exclusive and only a single option can be selected, however in the future available categories will expand.

content_warningslist of enumsOptional
Allow researchers to define content warnings for their study. At present these options are mutually exclusive and only a single option can be selected, however in the future available warnings will expand.
Allowed values:
content_warning_detailsstringOptional<=1000 characters
Allow researchers to add further details about their content warning.
metadatastring or nullOptional
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.
credential_pool_idstring or nullOptional
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](#tag/Credentials) for managing credential pools.
has_credentialsbooleanOptional
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.
data_collection_methodenum or nullOptional
**Optional.** Specifies the data collection method for the study. - `DC_TOOL`: Use AI Task Builder for data annotation and collection tasks (legacy value). - `AI_TASK_BUILDER`: Use AI Task Builder for data annotation and 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.
Allowed values:
data_collection_idstring or nullOptional

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

Required when data_collection_method is set to DC_TOOL or AI_TASK_BUILDER.

data_collection_metadataobject or nullOptional
**Optional.** Additional metadata for configuring AI Task Builder data collection behavior. Only used when `data_collection_method` is set to `DC_TOOL` or `AI_TASK_BUILDER`. **Properties:** - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used. - Minimum: 1 - Default: 1 (if not provided) **Example:** ```json { "annotators_per_task": 5 } ``` **Important:** You must include `annotators_per_task` to control how many participants annotate each task. This cannot be changed after the study is published.
access_detailslist of objects or nullOptional

Array of access_details, which integrates with taskflow.

While this field is nullable, you must provide one of access_details or external_study_url.

The sum of all access_details must add to the total_available_places field, however the values can be different for an individual access_detail.

is_external_study_url_securebooleanOptional
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: ```json { "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: ```json { "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>", ... } } ``` For example: ```json { "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" } } ``` **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](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get). - The JWT hasn't expired, by checking the `exp` claim. - The `aud` claim is the correct domain for your tool. - The `prolific` value matches your expected payload as set in the `external_study_url` property.
naivety_distribution_ratedouble or nullOptional0-1Deprecated
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.

Response

Updated
access_detailslist of objects or null

Array of access_details, which integrates with taskflow.

While this field is nullable, you must provide one of access_details or external_study_url.

The sum of all access_details must add to the total_available_places field, however the values can be different for an individual access_detail.

completion_codeslist of objects or null

Specify at least one completion code for your study. A participant will enter one of these codes when they complete your study.

Each code must be unique within a study.

You can specify as many actions as you like per code. However, some actions can’t be used together (e.g. AutomaticallyApprove and ManuallyReview).

content_warning_detailsstring or null<=1000 characters
Allow researchers to add further details about their content warning.
content_warningslist of enums or null
Allow researchers to define content warnings for their study. At present these options are mutually exclusive and only a single option can be selected, however in the future available warnings will expand.
Allowed values:
credential_pool_idstring or null
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](#tag/Credentials) for managing credential pools.
data_collection_idstring or null

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

Required when data_collection_method is set to DC_TOOL or AI_TASK_BUILDER.

data_collection_metadataobject or null
**Optional.** Additional metadata for configuring AI Task Builder data collection behavior. Only used when `data_collection_method` is set to `DC_TOOL` or `AI_TASK_BUILDER`. **Properties:** - `annotators_per_task` (integer): Number of annotators per task. **This field must be provided if you want multiple annotators per task.** Without this field, the default value of 1 will be used. - Minimum: 1 - Default: 1 (if not provided) **Example:** ```json { "annotators_per_task": 5 } ``` **Important:** You must include `annotators_per_task` to control how many participants annotate each task. This cannot be changed after the study is published.
data_collection_methodenum or null
**Optional.** Specifies the data collection method for the study. - `DC_TOOL`: Use AI Task Builder for data annotation and collection tasks (legacy value). - `AI_TASK_BUILDER`: Use AI Task Builder for data annotation and 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.
Allowed values:
descriptionstring or null
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.
device_compatibilitylist of enums or null
Add all devices that participants can use. You can include one or more options. An empty array indicates that all options are available.
Allowed values:
estimated_completion_timedouble or null>=1
Estimated duration in minutes of the experiment or survey
external_study_urlstring or null
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%}}`
filter_set_idstring or null

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

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

filter_set_versioninteger or null
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.
filterslist of objects or null
Array of filters. Use empty array for "Everyone"
has_credentialsboolean or null
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.
idstring or null

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

internal_namestring or null
Internal name of the study, not shown to participants
is_external_study_url_secureboolean or null
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: ```json { "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: ```json { "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>", ... } } ``` For example: ```json { "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" } } ``` **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](#tag/Well-Known-Endpoints/paths/~1.well-known~1study~1jwks.json/get). - The JWT hasn't expired, by checking the `exp` claim. - The `aud` claim is the correct domain for your tool. - The `prolific` value matches your expected payload as set in the `external_study_url` property.
maximum_allowed_timedouble or null
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
metadatastring or null
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.
namestring or null
Public name or title of the study
peripheral_requirementslist of enums or null
Add all requirements that participants have to meet. An empty array indicates that there are no extra peripheral requirements.
Allowed values:
projectstring or null
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.
prolific_id_optionenum or null

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.

Allowed values:
rewarddouble or null
How much are you going to pay the participants in cents. We use the currency of your account.
statusenum or null

Status of the study. Read only.

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

study_labelslist of enums or null

This field allows you to tag studies with information about the type/topic of the study and the kind of work involved in completing it.

We plan to make this information available to participants for easier self-selection. At present these options are mutually exclusive and only a single option can be selected, however in the future available categories will expand.

submissions_configobject or null

Advanced: This helps with faster data collection. Your survey system will need to handle providing a unique experience each time the participant takes the study.

Configuration related to study submissions. The purpose of this field is to capture any configuration options that impact the submissions made by participants in a study.

total_available_placesdouble or null>=1

How many participants are you looking to recruit.

Note: This field is optional when data_collection_method is set to DC_TOOL or AI_TASK_BUILDER (AI Task Builder), as the total available places are automatically calculated from the batch configuration.

naivety_distribution_ratedouble or null0-1Deprecated
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.

Errors