Update a study

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.

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

Note: This field is optional when data_collection_method is set to AI_TASK_BUILDER_BATCH or AI_TASK_BUILDER_COLLECTION. When omitted, a default COMPLETED code with a MANUALLY_REVIEW action is auto-generated. When provided, AITB studies must include exactly one code with code_type of COMPLETED and an action of MANUALLY_REVIEW or AUTOMATICALLY_APPROVE.

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.

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.

Optional. Additional metadata for configuring AI Task Builder data annotation behavior. Only used when data_collection_method is set to AI_TASK_BUILDER_BATCH.

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:

1
{
2
  "annotators_per_task": 5
3
}

Important: You must include annotators_per_task to control how many participants annotate each task. After the study is published, this value can only be increased (not decreased), which will increase the total available places on the study.

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.

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%}}

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.

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.

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

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:

1
{
2
  "alg": "RS256",
3
  "kid": "<KEY_ID>",
4
  "typ": "JWT"
5
}

Where

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

Payload:

1
{
2
  "iss": "https://www.prolific.com",
3
  "iat": <CURRENT_TIME>,
4
  "exp": <CURRENT_TIME + 2 minutes>,
5
  "aud": "<EXTERNAL_STUDY_URL>",
6
  "sub": "<SESSION_ID>",
7
  "prolific":{
8
    "<QUERY_1>": "<VALUE_1>",
9
    "<QUERY_2>": "<VALUE_2>",
10
    ...
11
    "workspace_id": "<WORKSPACE_ID>",
12
    "organisation_id": "<ORGANISATION_ID>"
13
  }
14
}

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

1
{
2
  "iss": "https://www.prolific.com",
3
  "iat": 1740496135,
4
  "exp": 1740496255,
5
  "aud": "https://x.com?STUDY_ID=1&...",
6
  "sub": "1234",
7
  "prolific":{
8
    "STUDY_ID": "abcd",
9
    "SESSION_ID": "1234",
10
    "PROLIFIC_PID": "xyz",
11
    "workspace_id": "507f1f77bcf86cd799439011",
12
    "organisation_id": "507f191e810c19729de860ea"
13
  }
14
}

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

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

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.

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.

Status of the study. Read only.

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

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.

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.

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.

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.