Sign in

v4

latestOpenAPI 3.1.02026-07-31121440441.0 KB
studies

Update a study

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
  • 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.
  • data_collection_metadata.annotators_per_task: For AI Task Builder Batch studies, you can increase the number of annotators per task. This will automatically recalculate total_available_places based on the number of task groups multiplied by the new value. Note: This value can only be increased, not decreased, on a published study.
  • 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.
patch/api/v1/studies/{id}/

Path parameters

idstring required

Study id

Headers

Authorizationstring required

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>.

Request body

namestring

Public name or title of the study

internal_namestring nullable

Internal name of the study, not shown to participants

descriptionstring

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_urlstring

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_option'question' | 'url_parameters' | 'not_required'

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.

total_available_placesnumber double

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_completion_timeinteger

Estimated duration in minutes of the experiment or survey

maximum_allowed_timenumber double

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

rewardnumber double

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

device_compatibilityBaseStudyDeviceCompatibilityItems[]

Add all devices that participants can use. You can include one or more options.

An empty array indicates that all options are available.

peripheral_requirementsBaseStudyPeripheralRequirementsItems[]

Add all requirements that participants have to meet.

An empty array indicates that there are no extra peripheral requirements.

filter_set_idstring nullable

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.

filter_set_versioninteger nullable

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.

naivety_distribution_ratenumber double nullable

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.

projectstring

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.

study_labelsBaseStudyStudyLabelsItems[]

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_warningsBaseStudyContentWarningsItems[]

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.

content_warning_detailsstring

Allow researchers to add further details about their content warning.

metadatastring nullable

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 nullable

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.

has_credentialsboolean

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_method'AI_TASK_BUILDER_BATCH' | 'AI_TASK_BUILDER_COLLECTION'

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.

data_collection_idstring nullable

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.

is_external_study_url_secureboolean

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).

Response

Updated

namestring required

Public name or title of the study

internal_namestring nullable

Internal name of the study, not shown to participants

descriptionstring required

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_urlstring required

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_option'question' | 'url_parameters' | 'not_required' required

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.

total_available_placesnumber double required

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_completion_timeinteger required

Estimated duration in minutes of the experiment or survey

maximum_allowed_timenumber double

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

rewardnumber double required

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

device_compatibilityCreateStudyDeviceCompatibilityItems[]

Add all devices that participants can use. You can include one or more options.

An empty array indicates that all options are available.

peripheral_requirementsCreateStudyPeripheralRequirementsItems[]

Add all requirements that participants have to meet.

An empty array indicates that there are no extra peripheral requirements.

filter_set_idstring nullable

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.

filter_set_versioninteger nullable

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.

naivety_distribution_ratenumber double nullable

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.

projectstring

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.

study_labelsCreateStudyStudyLabelsItems[]

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_warningsCreateStudyContentWarningsItems[]

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.

content_warning_detailsstring

Allow researchers to add further details about their content warning.

metadatastring nullable

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 nullable

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.

has_credentialsboolean

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_method'AI_TASK_BUILDER_BATCH' | 'AI_TASK_BUILDER_COLLECTION'

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.

data_collection_idstring nullable

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.

is_external_study_url_secureboolean

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).
idstring

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

status'UNPUBLISHED' | 'SCHEDULED' | 'PUBLISHING' | 'ACTIVE' | 'AWAITING REVIEW' | 'PAUSED' | 'COMPLETED'

Status of the study. Read only.

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

is_ready_to_publishboolean

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