Prolific API

https://docs.prolific.com/docs/api-docs/
Admin
The Prolific API provides programmatic access for researchers to manage studies, participants, and...
Tokens:187,443
Snippets:688
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup AI Task Builder Batch

Source: https://docs.prolific.com/docs/api-docs/public/studies

Initiates the setup process for an AI Task Builder batch, creating tasks based on configuration. The dataset must be in a 'READY' status before starting.

```APIDOC
## POST /api/v1/data-collection/batches/{batch_id}/setup

### Description
Sets up all tasks within an AI Task Builder batch according to your configuration. The dataset must be in a 'READY' status. Upon successful invocation, the setup process begins asynchronously, and the batch status changes to 'PROCESSING'. The setup is complete when the batch status changes to 'READY'.

### Method
POST

### Endpoint
`/api/v1/data-collection/batches/{batch_id}/setup`

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the AI Task Builder batch.

#### Header Parameters
- **Authorization** (string) - Required - Prolific API token

#### Request Body
- **dataset_id** (string) - Required - The ID of the dataset being configured into tasks.
- **tasks_per_group** (number) - Optional - The number of tasks to be presented to each annotator. Defaults to 1.

### Request Example
```json
{
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "tasks_per_group": 3
}
```

### Response
#### Success Response (202)
Accepted

#### Error Response (4XX)
```json
{
  "error": {
    "status": 0,
    "error_code": 0,
    "title": "string",
    "detail": "string",
    "additional_information": "string",
    "traceback": "string",
    "interactive": true
  }
}
```
```

--------------------------------

### Get Project Response Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example JSON response for retrieving project details. This includes project ID, title, description, owner, associated users, workspace, and distribution rate.

```json
{
  "id": "62fce6fff0a78eb4f3ebc09c",
  "title": "My project",
  "description": "This project is for...",
  "owner": "60a42f4c693c29420793cb73",
  "users": [
    {
      "id": "60a42f4c693c29420793cb73",
      "name": "Joe Soap",
      "email": "joe.soap@gmail.com",
      "roles": [
        "PROJECT_EDITOR"
]
}
],
  "workspace": "60a42f4c693c29420793cb73",
  "naivety_distribution_rate": 0.5

}
```

--------------------------------

### Prolific API Get Filter Distribution Request Example

Source: https://docs.prolific.com/docs/api-docs/public

This example demonstrates how to make a GET request to the Prolific API to retrieve the distribution of a specific filter. It includes path parameters like the filter ID and query parameters such as workspace ID and distribution filters. An Authorization header is required for authentication.

```http
GET /api/v1/filters/{id}/distribution/ HTTP/1.1
Host: api.prolific.com
Authorization: Bearer YOUR_API_TOKEN

Query Parameters:
workspace_id: YOUR_WORKSPACE_ID
distribution_filters: fact-checking,evaluation-accuracy,evaluation-reasoning,structured-writing,fact-checking-hours-of-experience
```

--------------------------------

### Curl Example for Getting Taskflow Progress

Source: https://docs.prolific.com/docs/api-docs/public

This example shows how to retrieve taskflow progress using cURL. It requires the study ID as a path parameter and an Authorization token in the header. The response provides details on participant allocation for each task within the study.

```bash
curl -X GET https://api.prolific.com/api/v1/studies/{id}/access-details-progress/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

--------------------------------

### Show Study Cost API Request Example (Conceptual)

Source: https://docs.prolific.com/docs/api-docs/public/studies

This conceptual example demonstrates how to request cost information for a study, with an option to get the projected cost. It requires the study ID in the path, an optional 'is_projected' query parameter, and an Authorization header.

```http
GET /api/v1/studies/{id}/cost/?is_projected=true
Host: api.prolific.com
Authorization: Bearer YOUR_API_TOKEN

```

--------------------------------

### Setup AI Task Builder Batch

Source: https://docs.prolific.com/docs/api-docs/public

Initiates the setup process for an AI Task Builder batch. The referenced dataset must be in 'READY' status. The batch status will change to 'PROCESSING' upon successful invocation and complete when it returns to 'READY'.

```APIDOC
## POST /api/v1/data-collection/batches/{batch_id}/setup

### Description
Sets up tasks within an AI Task Builder batch based on configuration. Requires the dataset to be in 'READY' status. The process runs asynchronously, updating the batch status to 'PROCESSING' and eventually back to 'READY' upon completion.

### Method
POST

### Endpoint
/api/v1/data-collection/batches/{batch_id}/setup

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the AI Task Builder batch.

#### Request Body
- **dataset_id** (string) - Required - The ID of the dataset being configured into tasks.
- **tasks_per_group** (number) - Optional - The number of tasks to present to each annotator. Defaults to 1.

### Request Example
```json
{
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "tasks_per_group": 3
}
```

### Response
#### Success Response (202)
Accepted

#### Error Response (4XX)
```json
{
  "error": {
    "status": 0,
    "error_code": 0,
    "title": "string",
    "detail": "string",
    "additional_information": "string",
    "traceback": "string",
    "interactive": true
  }
}
```
```

--------------------------------

### Curl Example for Predicted Recruitment Time

Source: https://docs.prolific.com/docs/api-docs/public

This example demonstrates how to get the predicted recruitment time for a study using cURL. It requires the study ID as a path parameter and an Authorization token in the header. The prediction is based on a machine learning model and estimates the time from publish to the start of the final submission.

```bash
curl -X GET https://api.prolific.com/api/v1/studies/{study_id}/predicted-recruitment-time/ \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

--------------------------------

### Setup AI Task Builder Batch

Source: https://docs.prolific.com/docs/api-docs/public/studies

Initiates the setup process for an AI Task Builder batch, creating tasks based on the provided configuration. The dataset must be in 'READY' status. Upon successful invocation, the batch status changes to 'PROCESSING' and will be 'READY' upon completion. Requires a Prolific API token for authorization.

```json
{
  "dataset_id": "8c4c51f1-f6f3-43bc-b65d-7415e8ef22c0",
  "tasks_per_group": 3
}
```

--------------------------------

### Publish Study Request Example

Source: https://docs.prolific.com/docs/api-docs/public

Example of a request body to publish an AI Task Builder study.

```APIDOC
## POST /studies

### Description
Publishes an AI Task Builder study to the Prolific platform.

### Method
POST

### Endpoint
/studies

### Request Body
- **name** (string) - Required - The name of the study.
- **internal_name** (string) - Required - The internal name for the batch.
- **description** (string) - Required - HTML description of the study instructions.
- **prolific_id_option** (string) - Required - Option for Prolific ID collection (e.g., 'not_required').
- **total_available_places** (integer) - Required - The total number of places available for the study.
- **estimated_completion_time** (integer) - Required - Estimated completion time in minutes.
- **maximum_allowed_time** (integer) - Required - Maximum allowed time in minutes.
- **reward** (integer) - Required - Reward amount in cents.
- **filters** (array) - Optional - Filters to apply to participant selection.
  - **filter_id** (string) - Required - The ID of the filter.
  - **selected_values** (array) - Required - The values for the filter.
- **study_labels** (array) - Optional - Labels for the study.
- **data_collection_method** (string) - Required - Method for data collection (e.g., 'DC_TOOL').
- **data_collection_id** (string) - Required - The ID of the data collection batch or dataset (e.g., '{{TASK_BUILDER_BATCH_ID}}').

### Request Example
```json
{
  "name": "AI Response Evaluation Task",
  "internal_name": "Internal Task Batch Name",
  "description": "<h1>Instructions for Selecting the Best Response</h1><p>Your task is to annotate the data.</p>",
  "prolific_id_option": "not_required",
  "total_available_places": 3,
  "estimated_completion_time": 6,
  "maximum_allowed_time": 15,
  "reward": 120,
  "filters": [
    {
      "filter_id": "participant_group_allowlist",
      "selected_values": [
        "123458388bd36ffaae123456"
      ]
    }
  ],
  "study_labels": [
    "ai_annotation"
  ],
  "data_collection_method": "DC_TOOL",
  "data_collection_id": "{{TASK_BUILDER_BATCH_ID}}"
}
```

### Response
#### Success Response (200)
- **study_id** (string) - The ID of the created study.
- **study_url** (string) - The URL to the published study.
```

--------------------------------

### Get AI Task Builder Instructions API Endpoint (HTTP)

Source: https://docs.prolific.com/docs/api-docs/public

Details the GET request for retrieving AI Task Builder instructions. It specifies the path parameter 'batch_id', required headers like 'Authorization', and potential response codes (200 for success, 4XX for errors).

```http
GET /api/v1/data-collection/batches/{batch_id}/instructions
Host: api.prolific.com
Authorization: Bearer YOUR_API_TOKEN
```

--------------------------------

### Get project

Source: https://docs.prolific.com/docs/api-docs/public

Gets a project's details.

```APIDOC
## GET /api/v1/projects/{project_id}/

### Description
Gets a project's details.

### Method
GET

### Endpoint
/api/v1/projects/{project_id}/

### Parameters
#### Path Parameters
- **project_id** (string) - Required - Project id

#### Header Parameters
- **Authorization** (string) - Required

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the project.
- **title** (string) - The title of the project.
- **description** (string) - A description of the project.
- **owner** (string) - The ID of the user who owns the project.
- **users** (array) - A list of users associated with the project.
  - **id** (string) - The unique identifier for the user.
  - **name** (string) - The name of the user.
  - **email** (string) - The email address of the user.
  - **roles** (array) - The roles of the user within the project.
- **workspace** (string) - The ID of the workspace the project belongs to.
- **naivety_distribution_rate** (number) - The naivety distribution rate for the project.

#### Response Example (200)
```json
{
  "id": "62fce6fff0a78eb4f3ebc09c",
  "title": "My project",
  "description": "This project is for...",
  "owner": "60a42f4c693c29420793cb73",
  "users": [
    {
      "id": "60a42f4c693c29420793cb73",
      "name": "Joe Soap",
      "email": "joe.soap@gmail.com",
      "roles": [
        "PROJECT_EDITOR"
      ]
    }
  ],
  "workspace": "60a42f4c693c29420793cb73",
  "naivety_distribution_rate": 0.5
}
```
```

--------------------------------

### Get AI Task Builder Instructions API Endpoint

Source: https://docs.prolific.com/docs/api-docs/public/studies

This section documents the API endpoint for retrieving instructions for an AI Task Builder batch. It specifies the HTTP method (GET), path parameters, required headers (Authorization), and potential response codes (200 for success, 4XX for errors).

```http
get /api/v1/data-collection/batches/{batch_id}/instructions
```

--------------------------------

### Upload Files to Dataset Request Example (cURL)

Source: https://docs.prolific.com/docs/api-docs/public

This example demonstrates how to upload multiple files to a specific dataset using a cURL command. It utilizes multipart/form-data to send the files, with 'dataset_id' as a path parameter and 'files' as the form field.

```bash
curl -X POST https://api.prolific.com/api/v1/data-collection/datasets/{dataset_id}/upload \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "files=@/path/to/your/file1.csv" \
  -F "files=@/path/to/your/file2.txt"
```

--------------------------------

### Get Filter Distribution API Request (Python)

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example Python code demonstrating how to call the Prolific API to get the distribution of a specific filter. This requires an API token for authorization and specifies the filter ID and workspace ID.

```python
import requests

api_token = "YOUR_API_TOKEN"
filter_id = "fact-checking"
workspace_id = "YOUR_WORKSPACE_ID"

headers = {
    "Authorization": api_token
}

params = {
    "workspace_id": workspace_id,
    "distribution_filters": filter_id
}

response = requests.get("https://api.prolific.com/api/v1/filters/{id}/distribution/", headers=headers, params=params)

if response.status_code == 200:
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)
```

--------------------------------

### Create AI Task Builder Instructions

Source: https://docs.prolific.com/docs/api-docs/public/studies

Allows you to create instructions for an AI Task Builder batch by providing a list of instruction objects.

```APIDOC
## POST /api/v1/data-collection/batches/{batch_id}/instructions

### Description
Create instructions for a Task Builder batch.

### Method
POST

### Endpoint
https://api.prolific.com/api/v1/data-collection/batches/{batch_id}/instructions

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the AI Task Builder batch.

#### Header Parameters
- **Authorization** (string) - Required - Prolific API token.

#### Request Body
- **instructions** (Array) - Required - An array of objects, where each object represents an instruction for the AI Task Builder batch.
  - Each instruction object can have the following properties:
    - **type** (string) - Required - Enum: "multiple_choice", "free_text", "multiple_choice_with_free_text". The type of instruction.
    - **created_by** (string) - Required - The user who created the instruction.
    - **description** (string) - Required - The instruction text.
    - **options** (Array of objects) - Required for "multiple_choice" and "multiple_choice_with_free_text" types. The options for the instruction.
      - Each option object for "multiple_choice" can have:
        - **label** (string) - The display text for the option.
        - **value** (string) - The value associated with the option.
      - Each option object for "multiple_choice_with_free_text" must have:
        - **label** (string) - Required - The display text for the option.
        - **value** (string) - Required - The value associated with the option.
        - **heading** (string) - Required - The heading or context for the option.
    - **answer_limit** (object) - Optional - For "multiple_choice_with_free_text" type. Defines the limit for selecting answers.
      - **type** (string) - The type of limit (e.g., "integer").
      - **description** (string) - Description of the limit.

### Request Example
```json
[
  {
    "type": "multiple_choice",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
      },
      {
        "label": "Response 2",
        "value": "response2"
      }
    ]
  },
  {
    "type": "free_text",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice."
  },
  {
    "type": "multiple_choice_with_free_text",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate and explain why.",
    "answer_limit": {
      "type": "integer",
      "description": "The maximum number of options a participant can select."
    },
    "options": {
      "type": "array",
      "description": "Required for multiple_choice_with_free_text type. The options for the instruction.",
      "items": {
        "type": "object",
        "required": [
          "label",
          "value",
          "heading"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "The display text for the option."
          },
          "value": {
            "type": "string",
            "description": "The value associated with the option."
          },
          "heading": {
            "type": "string",
            "description": "The heading or context for the option."
          }
        }
      }
    }
  }
]
```

### Response
#### Success Response (201)
- **type** (string) - The type of instruction.
- **batch_id** (string) - The ID of the batch the instruction belongs to.
- **created_by** (string) - The user who created the instruction.
- **description** (string) - The instruction text.
- **options** (Array) - The options for the instruction (if applicable).
- **id** (string) - The unique identifier of the created instruction.
- **created_at** (string) - The timestamp when the instruction was created.

#### Response Example
```json
[
  {
    "type": "multiple_choice",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
      },
      {
        "label": "Response 2",
        "value": "response2"
      }
    ],
    "id": "0192041c-470f-7336-8e3d-e03fc086a4e1",
    "created_at": "2024-09-18T07:50:15.055Z"
  },
  {
    "type": "free_text",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice.",
    "id": "0192041c-4710-7336-8e3d-e9b6149c0797",
    "created_at": "2024-09-18T07:50:15.056Z"
  }
]
```
```

--------------------------------

### Create AI Task Builder Instructions

Source: https://docs.prolific.com/docs/api-docs/public

Create instructions for a Task Builder batch. This endpoint allows you to define various types of instructions, such as multiple choice, free text, or a combination of both, for participants in an AI Task Builder batch.

```APIDOC
## POST /api/v1/data-collection/batches/{batch_id}/instructions

### Description
Create instructions for a Task Builder batch.

### Method
POST

### Endpoint
`/api/v1/data-collection/batches/{batch_id}/instructions`

### Parameters
#### Path Parameters
- **batch_id** (string) - Required - The unique identifier of the AI Task Builder batch.

#### Header Parameters
- **Authorization** (string) - Required - Prolific API token

#### Request Body
- **instructions** (array of objects) - Required - The instructions to create for the AI Task Builder batch.
  - **type** (string) - Required - Enum: "multiple_choice", "free_text", "multiple_choice_with_free_text"
  - **created_by** (string) - Required - The user who created the instruction.
  - **description** (string) - Required - The instruction text.
  - **options** (array of objects) - Required for "multiple_choice" and "multiple_choice_with_free_text". The options for the instruction.
    - **label** (string) - Required - The display text for the option.
    - **value** (string) - Required - The value associated with the option.
    - **heading** (string) - Required for "multiple_choice_with_free_text". The heading or context for the option.
  - **answer_limit** (object) - Required for "multiple_choice_with_free_text". The maximum number of options a participant can select.
    - **type** (string) - "integer"
    - **description** (string) - "The maximum number of options a participant can select."

### Request Example
```json
[
  {
    "type": "multiple_choice",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
      },
      {
        "label": "Response 2",
        "value": "response2"
      }
    ]
  },
  {
    "type": "free_text",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice."
  },
  {
    "type": "multiple_choice_with_free_text",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate and explain why.",
    "answer_limit": {
      "type": "integer",
      "description": "The maximum number of options a participant can select."
    },
    "options": {
      "type": "array",
      "description": "Required for multiple_choice_with_free_text type. The options for the instruction.",
      "items": {
        "type": "object",
        "required": [
          "label",
          "value",
          "heading"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "The display text for the option."
          },
          "value": {
            "type": "string",
            "description": "The value associated with the option."
          },
          "heading": {
            "type": "string",
            "description": "The heading or context for the option."
          }
        }
      }
    }
  }
]
```

### Response
#### Success Response (201)
- **type** (string) - The type of instruction.
- **batch_id** (string) - The ID of the batch the instruction belongs to.
- **created_by** (string) - The user who created the instruction.
- **description** (string) - The instruction text.
- **options** (array of objects) - The options for the instruction (if applicable).
  - **label** (string) - The display text for the option.
  - **value** (string) - The value associated with the option.
- **id** (string) - The unique identifier of the instruction.
- **created_at** (string) - The timestamp when the instruction was created.

#### Response Example
```json
[
  {
    "type": "multiple_choice",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
      },
      {
        "label": "Response 2",
        "value": "response2"
      }
    ],
    "id": "0192041c-470f-7336-8e3d-e03fc086a4e1",
    "created_at": "2024-09-18T07:50:15.055Z"
  },
  {
    "type": "free_text",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice.",
    "id": "0192041c-4710-7336-8e3d-e9b6149c0797",
    "created_at": "2024-09-18T07:50:15.056Z"
  }
]
```
```

--------------------------------

### Get Taskflow Progress API Request Example (Conceptual)

Source: https://docs.prolific.com/docs/api-docs/public/studies

This conceptual example shows how to retrieve the taskflow progress for a study using the Prolific API. It requires the study ID in the path and an Authorization header. The response indicates progress for each access detail.

```http
GET /api/v1/studies/{id}/access-details-progress/
Host: api.prolific.com
Authorization: Bearer YOUR_API_TOKEN

```

--------------------------------

### Introduction to Prolific API

Source: https://docs.prolific.com/docs/api-docs/public

Overview of the Prolific API's capabilities, including study management, submissions, bonuses, messaging, workspaces, surveys, participant groups, and webhooks.

```APIDOC
## Introduction to Prolific API

This API allows you to recruit high-quality participants and manage your research workflows programmatically through your own app. Key features include:

*   **Study**: Create, update, and publish your Prolific studies.
*   **Submissions**: Approve and reject submissions programmatically.
*   **Bonus**: Pay a bonus to high-performing submissions.
*   **Messages**: Send and receive participant messages.
*   **Workspaces**: Collaborate with your teammates and organize research.
*   **Survey**: Create quick prescreening studies.
*   **Participant groups**: Manage lists of participants for launching studies.
*   **Hooks**: Receive notifications for specific events on your studies.

**Note**: The API does not support account management features like topping up balances or user management. Advanced web application features may also not be available.
```

--------------------------------

### AI Task Builder Workflow

Source: https://docs.prolific.com/docs/api-docs/public

Overview of the AI Task Builder API workflow, detailing the steps from batch creation to fetching responses.

```APIDOC
## AI Task Builder Workflow

This outlines the typical workflow for using the AI Task Builder API:

1. **Create a batch**: Initiate a data collection project.
2. **Create a dataset**: Set up the data structure.
3. **Upload your data**: Upload data for task creation.
4. **Monitor dataset status**: Wait for dataset processing.
5. **Create instructions**: Define annotation guidelines.
6. **Set up the batch**: Configure batch with necessary details.
7. **Monitor batch status**: Ensure the batch is ready for study attachment.
8. **Create a study**: Create a study referencing the AI Task Builder batch.
9. **Publish the study**: Distribute tasks to annotators.
10. **Wait for task completion**: Allow annotators to complete tasks.
11. **Fetch responses**: Retrieve the completed annotations.
```

--------------------------------

### Curl Example for Getting Study Cost

Source: https://docs.prolific.com/docs/api-docs/public

This cURL example retrieves cost information for a study. It uses the study ID as a path parameter and requires an Authorization token in the header. The 'is_projected' query parameter can be added to fetch projected costs instead of current costs.

```bash
curl -X GET https://api.prolific.com/api/v1/studies/{id}/cost/?is_projected=true \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

--------------------------------

### Example JSON Response for Retrieving a Submission

Source: https://docs.prolific.com/docs/api-docs/public/studies

This is an example of the JSON response structure when retrieving a single submission. It provides detailed information about the submission, including completion status, entered code, participant details, start and completion timestamps, status, study ID, and any bonus payments.

```json
{
  "id": "625d4a831bcda2d59ac5a251",
  "completed_at": "2022-04-18T11:25:02.734000Z",
  "entered_code": "8E8AC860",
  "participant": "60bf9310e8dec401be6e9615",
  "started_at": "2022-04-18T11:24:51.395000Z",
  "status": "APPROVED",
  "study_id": "60aca280709ee40ec37d4885",
  "bonus_payments": [
    1000,
    2536
  ]
}
```

--------------------------------

### Create AI Task Builder Instructions Request Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public

This JSON payload demonstrates the structure for creating instructions in an AI Task Builder batch. It includes different instruction types such as multiple choice, free text, and a combination of both, specifying details like created by, description, and options. This is used to define the tasks participants will complete.

```json
[
  {
    "type": "multiple_choice",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
},
      {
        "label": "Response 2",
        "value": "response2"
}
]
},
  {
    "type": "free_text",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice."
},
  {
    "type": "multiple_choice_with_free_text",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate and explain why.",
    "answer_limit": {
      "type": "integer",
      "description": "The maximum number of options a participant can select."
},
    "options": {
      "type": "array",
      "description": "Required for multiple_choice_with_free_text type. The options for the instruction.",
      "items": {
        "type": "object",
        "required": [
          "label",
          "value",
          "heading"
],
        "properties": {
          "label": {
            "type": "string",
            "description": "The display text for the option."
},
          "value": {
            "type": "string",
            "description": "The value associated with the option."
},
          "heading": {
            "type": "string",
            "description": "The heading or context for the option."
}
}
}
}

]
```

--------------------------------

### Create AI Task Builder Instructions (JSON Request)

Source: https://docs.prolific.com/docs/api-docs/public/studies

This snippet demonstrates the JSON payload structure for creating AI Task Builder instructions. It includes examples for multiple_choice, free_text, and multiple_choice_with_free_text instruction types. Ensure the 'batch_id' is correctly provided in the URL.

```json
[
  {
    "type": "multiple_choice",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
      },
      {
        "label": "Response 2",
        "value": "response2"
      }
    ]
  },
  {
    "type": "free_text",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice."
  },
  {
    "type": "multiple_choice_with_free_text",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate and explain why.",
    "answer_limit": {
      "type": "integer",
      "description": "The maximum number of options a participant can select."
    },
    "options": {
      "type": "array",
      "description": "Required for multiple_choice_with_free_text type. The options for the instruction.",
      "items": {
        "type": "object",
        "required": [
          "label",
          "value",
          "heading"
        ],
        "properties": {
          "label": {
            "type": "string",
            "description": "The display text for the option."
          },
          "value": {
            "type": "string",
            "description": "The value associated with the option."
          },
          "heading": {
            "type": "string",
            "description": "The heading or context for the option."
          }
        }
      }
    }
  }
]
```

--------------------------------

### Response Sample for Retrieving User Information

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example of a successful response (200 OK) when retrieving user information, including the user's ID and email.

```JSON
{
  "id": "60a42f4c693c29420793cb73",
  "email": "your@email.com"
}
```

--------------------------------

### Get All Surveys Response Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public

Example response for retrieving all surveys associated with a researcher. Includes survey details like ID, creation/modification dates, researcher ID, sections, questions, and title.

```json
{
  "results": [
    {
      "_id": "string",
      "date_created": "2022-05-27T08:43:12",
      "date_modified": "2022-05-27T08:43:12",
      "researcher_id": "7172727272",
      "sections": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "questions": [
            {
              "answers": [
                {
                  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                  "value": "Potato"
                }
              ],
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "title": "What is your favourite root vegetable?",
              "type": "single"
            }
          ],
          "title": "Root vegetables"
        }
      ],
      "questions": [
        {
          "answers": [
            {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "value": "Potato"
            }
          ],
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "title": "What is your favourite root vegetable?",
          "type": "single"
        }
      ],
      "title": "A survey about vegetables"
    }
  ]
}
```

--------------------------------

### Create AI Task Builder Instructions Response Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public

This JSON represents a successful creation response for AI Task Builder instructions. It includes details about the created instructions, such as their type, batch ID, creator, description, and unique IDs, along with creation timestamps. This confirms the instructions have been added to the specified batch.

```json
[
  {
    "type": "multiple_choice",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Choose the LLM response which is more accurate.",
    "options": [
      {
        "label": "Response 1",
        "value": "response1"
},
      {
        "label": "Response 2",
        "value": "response2"
}
],
    "id": "0192041c-470f-7336-8e3d-e03fc086a4e1",
    "created_at": "2024-09-18T07:50:15.055Z"
},
  {
    "type": "free_text",
    "batch_id": "01974850-9e29-744a-811c-b26612812345",
    "created_by": "Sean",
    "description": "Please share the reasons for your choice.",
    "id": "0192041c-4710-7336-8e3d-e9b6149c0797",
    "created_at": "2024-09-18T07:50:15.056Z"
}

]
```

--------------------------------

### Get All Surveys Response Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example JSON response for retrieving a list of all surveys associated with a researcher. It includes survey metadata such as IDs, creation/modification dates, researcher ID, and survey content (sections and questions).

```json
{
  "results": [
    {
      "_id": "string",
      "date_created": "2022-05-27T08:43:12",
      "date_modified": "2022-05-27T08:43:12",
      "researcher_id": "7172727272",
      "sections": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "questions": [
            {
              "answers": [
                {
                  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
                  "value": "Potato"
}
],
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "title": "What is your favourite root vegetable?",
              "type": "single"
}
],
          "title": "Root vegetables"
}
],
      "questions": [
        {
          "answers": [
            {
              "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
              "value": "Potato"
}
],
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "title": "What is your favourite root vegetable?",
          "type": "single"
}
],
      "title": "A survey about vegetables"
}
]

}
```

--------------------------------

### GET /api/v1/studies/{study_id}/predicted-recruitment-time/

Source: https://docs.prolific.com/docs/api-docs/public

Returns the predicted recruitment time for the study if it was published right now, based on a machine learning model. The recruitment time is the time from publish to the time when the final participant starts their submission. It does not account for the time to complete the submission.

```APIDOC
## Show Study predicted recruitment time

Returns the predicted recruitment time for the study if it was published right now, based on a machine learning model. The recruitment time is the time from publish to the time when the final participant starts their submission. It does not account for the time to complete the submission.

### Method
GET

### Endpoint
`/api/v1/studies/{study_id}/predicted-recruitment-time/
`

### Parameters
#### Path Parameters
- **study_id** (string) - Required - Study id

#### Header Parameters
- **Authorization** (string) - Required

### Responses
#### Success Response (200)
- Description: Return the predicted recruitment time for the study
- **predicted_recruitment_time** (integer) - The predicted recruitment time in hours

#### Error Response (4XX)
- Description: Error

### Response Example (200)
```json
{
  "predicted_recruitment_time": 48
}
```
```

--------------------------------

### Example Response for Listing Eligibility Requirements

Source: https://docs.prolific.com/docs/api-docs/public/studies

This JSON structure represents a sample response from the /api/v1/eligibility-requirements/ endpoint, showing a list of requirements with their details, including attributes and query information.

```json
{
  "results": [
    {
      "_cls": "SelectAnswerEligibilityRequirement",
      "attributes": [
        {
          "index": 5,
          "name": "string",
          "value": "true"
        }
      ],
      "query": {
        "id": "54ac6ea9fdf99b2204feb899",
        "question": "What is your first language?"
      }
    }
  ]
}
```

--------------------------------

### Create Workspace Response JSON

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example JSON response after successfully creating a workspace. It includes the workspace's ID, title, owner information, associated users, projects, and wallet details.

```json
{
  "id": "62fce6fff0a78eb4f3ebc09c",
  "title": "My workspace",
  "description": "This workspace does...",
  "owner": "60a42f4c693c29420793cb73",
  "users": [
    {
      "id": "60a42f4c693c29420793cb73",
      "name": "Joe Soap",
      "email": "joe.soap@gmail.com",
      "roles": [
        "WORKSPACE_ADMIN"
      ]
    }
  ],
  "projects": [
    {
      "id": "60a42f4c693c29420793cb73"
    }
  ],
  "wallet": "61a65c06b084910b3f0c00d6"
}
```

--------------------------------

### Get AI Task Builder Batch Status Response Sample (JSON)

Source: https://docs.prolific.com/docs/api-docs/public/studies

This JSON response indicates the current status of a specific AI Task Builder batch. The status can be, for example, 'UNINITIALISED'. This endpoint is useful for monitoring the state of your data collection batches.

```json
{
  "status": "UNINITIALISED"
}
```

--------------------------------

### Create Project JSON Response Sample

Source: https://docs.prolific.com/docs/api-docs/public/studies

This JSON response details a successfully created project. It includes the project's ID, title, description, owner, associated users, workspace ID, and the set naivety distribution rate. This is the typical response for the 'Create a project' endpoint upon success.

```json
{
  "id": "62fce6fff0a78eb4f3ebc09c",
  "title": "My project",
  "description": "This project is for...",
  "owner": "60a42f4c693c29420793cb73",
  "users": [
    {
      "id": "60a42f4c693c29420793cb73",
      "name": "Joe Soap",
      "email": "joe.soap@gmail.com",
      "roles": [
        "PROJECT_EDITOR"
      ]
    }
  ],
  "workspace": "60a42f4c693c29420793cb73",
  "naivety_distribution_rate": 0.5
}
```

--------------------------------

### GET Filter Sets API Response Sample (200 OK)

Source: https://docs.prolific.com/docs/api-docs/public/studies

Example of a successful response when listing all filter sets in a workspace. The response includes a 'results' array, where each object represents a filter set with its ID, workspace ID, name, filters, version, and status.

```json
{
  "results": [
    {
      "id": "644ab312af6bbc363b9d47c7",
      "workspace_id": "644aaabfaf6bbc363b9d47c6",
      "name": "Ambidextrous teenagers",
      "filters": [
        {
          "id": "handedness",
          "selected_values": [
            "2"
]
},
        {
          "id": "age",
          "selected_range": {
            "lower": 18,
            "upper": 19
}
}
],
      "version": 1,
      "is_locked": true,
      "is_deleted": false,
      "eligible_participant_count": 0
}
]

}
```

--------------------------------

### Response Samples

Source: https://docs.prolific.com/docs/api-docs/public/studies

This section provides example response structures for API requests, particularly for success cases.

```APIDOC
## Response Samples

### Success Response (200)

#### Content Type
application/json

### Response Example
```json
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "string",
      "alg": "RS256",
      "n": "string",
      "e": "string",
      "use": "sig",
      "key_ops": [
        "verify"
      ]
    }
  ]
}
```
```

--------------------------------

### POST /api/v1/submissions/bonus-payments/

Source: https://docs.prolific.com/docs/api-docs/public/studies

Sets up bonus payments for one or more participants or submissions within a study. This prepares the bonus payment but does not execute it.

```APIDOC
## POST /api/v1/submissions/bonus-payments/

### Description
Sets up bonus payments for one or more participants or submissions within a study. This prepares the bonus payment but does not execute it.

### Method
POST

### Endpoint
https://api.prolific.com/api/v1/submissions/bonus-payments/

### Headers
- **Authorization** (string) - Required - Bearer token for authentication.

### Request Body
- **study_id** (string) - Required - The ID of the study for which bonuses are being set up.
- **csv_bonuses** (string) - Required - A CSV formatted string where each line represents a bonus payment in the format `<participant_id>,<amount>` or `<submission_id>,<amount>`. Amount should be a decimal value representing the study currency (e.g., 4.25 for £4.25).

### Request Example
```json
{
  "study_id": "60f6acb180a7b59ac0621f9e",
  "csv_bonuses": "60ffe5c8371090c7041d43f8,4.25\n60ff44a1d00991f1dfe405d9,4.25"
}
```

### Response
#### Success Response (201)
- **id** (string) - The ID of the created bonus payment batch.
- **study** (string) - The ID of the study associated with the bonus payment.
- **amount** (number) - The total bonus amount excluding fees and VAT.
- **fees** (number) - The calculated fees for the bonus payment.
- **vat** (number) - The VAT amount applicable to the bonus payment.
- **total_amount** (number) - The total amount to be paid, including bonuses, fees, and VAT.

#### Response Example
```json
{
  "id": "621014cb8e9e0f81e387021f",
  "study": "620ca2735fcbba4fa2b3211a",
  "amount": 850,
  "fees": 283.34,
  "vat": 0,
  "total_amount": 1133.34
}
```
```
Tokens:
Raw