> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.prolific.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.prolific.com/_mcp/server. # Working with Collections A Task Builder Collection allows you to gather original data from participants. Unlike Batches where participants evaluate your data, Collections enable participants to submit their own content — images, files, text responses, and more. This guide covers the workflow for creating, configuring, and publishing a Collection. ## Workflow overview Create a collection: Define your collection structure including pages, instructions, and content blocks in a single request. Update the collection (optional): Modify pages, instructions, or configuration as needed. Create a study: Create a Prolific study that references your collection. Publish the study: Make the study available to participants. Retrieve responses: After participants complete the study, fetch their submitted data. ## Creating a collection Create a collection by sending a `POST` request to the collections endpoint. You can define the full structure — including pages, instructions, and content blocks — in a single request. ```bash POST /api/v1/data-collection/collections ``` ### Request structure A collection contains `collection_items` (pages), and each page contains `page_items` (instructions and content blocks). Participants progress through pages sequentially, completing the instructions on each page before moving to the next. Each item requires an `order` field to determine its position within its parent. ```json { "name": "Skin Condition Image Collection", "description": "Collecting images of minor skin conditions for medical AI training", "task_details": { "task_name": "Skin Condition Photo Submission", "task_introduction": "

Help us build a medical imaging dataset by submitting photos of minor skin conditions.

", "task_steps": "
  1. Review the consent information
  2. Answer questions about yourself
  3. Upload a clear photo of the affected area
" }, "collection_items": [ { "order": 1, "page_items": [ { "order": 1, "type": "multiple_choice", "description": "What is your skin type?", "answer_limit": 1, "options": [ { "label": "Type I - Very fair", "value": "type_1" }, { "label": "Type II - Fair", "value": "type_2" }, { "label": "Type III - Medium", "value": "type_3" }, { "label": "Type IV - Olive", "value": "type_4" }, { "label": "Type V - Brown", "value": "type_5" }, { "label": "Type VI - Dark", "value": "type_6" } ] }, { "order": 2, "type": "multiple_choice", "description": "What is your age range?", "answer_limit": 1, "options": [ { "label": "18-24", "value": "18-24" }, { "label": "25-34", "value": "25-34" }, { "label": "35-44", "value": "35-44" }, { "label": "45-54", "value": "45-54" }, { "label": "55-64", "value": "55-64" }, { "label": "65+", "value": "65+" } ] } ] }, { "order": 2, "page_items": [ { "order": 1, "type": "rich_text", "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible." }, { "order": 2, "type": "image", "url": "https://example.com/assets/photo-guidelines.png", "alt_text": "Example of a well-lit, in-focus photograph" }, { "order": 3, "type": "free_text", "description": "Briefly describe the skin condition shown in your image" }, { "order": 4, "type": "file_upload", "description": "Upload a clear photo of the affected area" } ] } ] } ``` ### Task details The optional `task_details` object provides context to participants: | Field | Type | Description | | ------------------- | ------ | -------------------------------- | | `task_name` | string | Title displayed to participants | | `task_introduction` | string | Introduction or general guidance | | `task_steps` | string | Steps participants should follow | All three fields support basic HTML formatting. ### Page items The `page_items` array can contain both **instructions** (which participants respond to) and **content blocks** (non-interactive content for context or guidance). #### Instruction types | Type | Description | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `multiple_choice` | Selection from a list of options. Use `answer_limit` to control how many options can be selected: `1` for single-select, `-1` for unlimited, or any number up to the total options. | | `free_text` | Open-ended text input | | `free_text_with_unit` | Text input with unit selection (e.g., measurements in cm/inches, currency amounts) | | `multiple_choice_with_free_text` | Selection from options, each with a heading and an associated free text field for additional input | | `file_upload` | File submission for images, documents, screenshots, or other files. Configurable file types, size limits, and file count requirements | #### Instruction fields All instructions require a `description` field containing the prompt or question text. **Multiple choice:** ```json { "order": 1, "type": "multiple_choice", "description": "What is your skin type?", "answer_limit": 1, "options": [ { "label": "Type I - Very fair", "value": "type_1" }, { "label": "Type II - Fair", "value": "type_2" }, { "label": "Type III - Medium", "value": "type_3" } ] } ``` Each option has a `label` (displayed to the participant) and a `value` (returned in responses). > **Note** > > By default, when there are 5 or more options, a dropdown is rendered instead of checkboxes or radio buttons. Set `disable_dropdown: true` to always use checkboxes/radio buttons. See [Instructions](/api-reference/task-builder/instructions) for full details. **Multiple choice with free text:** ```json { "order": 1, "type": "multiple_choice_with_free_text", "description": "Rate the following aspects of the image:", "answer_limit": -1, "options": [ { "label": "Good", "value": "lighting_good", "heading": "Lighting" }, { "label": "Good", "value": "focus_good", "heading": "Focus" }, { "label": "Good", "value": "framing_good", "heading": "Framing" } ] } ``` Each option requires a `heading` field, which groups the option under a labeled section. The associated free text field allows participants to provide additional context for their selection. **Free text:** ```json { "order": 1, "type": "free_text", "description": "Describe the affected area in your own words", "placeholder_text_input": "e.g. Small red patch on left forearm..." } ``` The optional `placeholder_text_input` field provides hint text displayed in the input field before the participant enters their response. **Free text with unit:** ```json { "order": 1, "type": "free_text_with_unit", "description": "What is your height?", "unit_options": [ { "label": "Centimeters", "value": "cm" }, { "label": "Inches", "value": "in" } ], "unit_position": "suffix" } ``` `unit_options` is a required array of at least two units, each with a `label` and `value`. `unit_position` controls whether the unit selector appears before (`"prefix"`) or after (`"suffix"`) the text input. See [Instructions](/api-reference/task-builder/instructions) for the full field reference including the optional `default_unit` field. #### Content block types | Type | Description | | ----------- | --------------------------------------------------------------------------------------- | | `image` | Display an image with alt text and optional caption | | `rich_text` | Formatted text content. Supports HTML (default) or Markdown via `content_format` field. | ### Content block schemas **Image content block:** ```json { "order": 1, "type": "image", "url": "https://example.com/reference-image.png", "alt_text": "Description of the image for accessibility", "caption": "Optional caption displayed below the image" } ``` The `url` must use HTTPS. The `alt_text` field is required for accessibility; `caption` is optional. **Rich text content block:** ```json { "order": 1, "type": "rich_text", "content": "

Instructions with bold and italic formatting.

" } ``` The `content` field accepts HTML by default. To use Markdown formatting, set `content_format` to `"markdown"` — the content will be converted to HTML server-side. If `content_format` is omitted, the content is treated as HTML. ```json { "order": 1, "type": "rich_text", "content": "# Instructions\nContent with **bold** and *italic* formatting.", "content_format": "markdown" } ``` ### Response A successful request returns the created collection with IDs assigned to the collection, pages, and page items: ```json { "id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b", "name": "Skin Condition Image Collection", "description": "Collecting images of minor skin conditions for medical AI training", "status": "draft", "collection_items": [ { "id": "0192a3b4-d6e7-7f8a-0b1c-2d3e4f5a6b7c", "order": 1, "page_items": [ { "id": "0192a3b4-e7f8-7a0b-1c2d-3e4f5a6b7c8d", "order": 1, "type": "multiple_choice", "description": "What is your skin type?", "answer_limit": 1, "options": [ { "label": "Type I - Very fair", "value": "type_1" }, { "label": "Type II - Fair", "value": "type_2" }, { "label": "Type III - Medium", "value": "type_3" }, { "label": "Type IV - Olive", "value": "type_4" }, { "label": "Type V - Brown", "value": "type_5" }, { "label": "Type VI - Dark", "value": "type_6" } ] }, { "id": "0192a3b4-f8a9-7b0c-1d2e-4f5a6b7c8d9e", "order": 2, "type": "multiple_choice", "description": "What is your age range?", "answer_limit": 1, "options": [ { "label": "18-24", "value": "18-24" }, { "label": "25-34", "value": "25-34" }, { "label": "35-44", "value": "35-44" }, { "label": "45-54", "value": "45-54" }, { "label": "55-64", "value": "55-64" }, { "label": "65+", "value": "65+" } ] } ] }, { "id": "0192a3b5-a9b0-7c1d-2e3f-5a6b7c8d9e0f", "order": 2, "page_items": [ { "id": "0192a3b5-b0c1-7d2e-3f4a-6b7c8d9e0f1a", "order": 1, "type": "rich_text", "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible." }, { "id": "0192a3b5-c1d2-7e3f-4a5b-7c8d9e0f1a2b", "order": 2, "type": "image", "url": "https://example.com/assets/photo-guidelines.png", "alt_text": "Example of a well-lit, in-focus photograph" }, { "id": "0192a3b5-d2e3-7f4a-5b6c-8d9e0f1a2b3c", "order": 3, "type": "free_text", "description": "Briefly describe the skin condition shown in your image" }, { "id": "0192a3b5-e3f4-7a5b-6c7d-9e0f1a2b3c4d", "order": 4, "type": "file_upload", "description": "Upload a clear photo of the affected area" } ] } ] } ``` ## Updating a collection Update an existing collection using a `PUT` request. You can modify any part of the collection — update existing items, add new ones, or remove items entirely. ```bash PUT /api/v1/data-collection/collections/{collection_id} ``` ### How updates work The `PUT` request performs a full replacement — the request body represents the complete desired state of the collection. Any pages or page items not included in the request will be removed. For example, if your collection has three pages and you send an update containing only two, the third page and all its contents will be deleted. > **Note** > > To preserve entity IDs across updates (useful for correlating responses with specific instructions), include the `id` field when sending existing items. Items sent without an `id` will be created as new entities with new IDs. ### Example: Adding a new page To add a consent page at the beginning of the collection, send a `PUT` request with the complete desired structure: ```json { "name": "Skin Condition Image Collection", "description": "Collecting images of minor skin conditions for medical AI training", "task_details": { "task_name": "Skin Condition Photo Submission", "task_introduction": "

Help us build a medical imaging dataset by submitting photos of minor skin conditions.

", "task_steps": "
  1. Review the consent information
  2. Answer questions about yourself
  3. Upload a clear photo of the affected area
" }, "collection_items": [ { "order": 1, "page_items": [ { "order": 1, "type": "rich_text", "content": "Before participating, please review and acknowledge the following:" }, { "order": 2, "type": "multiple_choice", "description": "Please confirm all of the following:", "answer_limit": 3, "options": [ { "label": "I understand my images may be used for AI training purposes", "value": "consent_ai_training" }, { "label": "I confirm I am over 18 years of age", "value": "consent_age" }, { "label": "I consent to participate in this study", "value": "consent_participate" } ] } ] }, { "order": 2, "page_items": [ { "order": 1, "type": "multiple_choice", "description": "What is your skin type?", "answer_limit": 1, "options": [ { "label": "Type I - Very fair", "value": "type_1" }, { "label": "Type II - Fair", "value": "type_2" }, { "label": "Type III - Medium", "value": "type_3" }, { "label": "Type IV - Olive", "value": "type_4" }, { "label": "Type V - Brown", "value": "type_5" }, { "label": "Type VI - Dark", "value": "type_6" } ] }, { "order": 2, "type": "multiple_choice", "description": "What is your age range?", "answer_limit": 1, "options": [ { "label": "18-24", "value": "18-24" }, { "label": "25-34", "value": "25-34" }, { "label": "35-44", "value": "35-44" }, { "label": "45-54", "value": "45-54" }, { "label": "55-64", "value": "55-64" }, { "label": "65+", "value": "65+" } ] } ] }, { "order": 3, "page_items": [ { "order": 1, "type": "rich_text", "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible." }, { "order": 2, "type": "image", "url": "https://example.com/assets/photo-guidelines.png", "alt_text": "Example of a well-lit, in-focus photograph" }, { "order": 3, "type": "free_text", "description": "Briefly describe the skin condition shown in your image" }, { "order": 4, "type": "file_upload", "description": "Upload a clear photo of the affected area" } ] } ] } ``` ## Publishing a collection To make your collection available to participants, create a Prolific study that references it. ```bash POST /api/v1/studies/ ``` When creating the study, set `data_collection_method` to `AI_TASK_BUILDER_COLLECTION` and provide your collection ID: ```json { "name": "Skin Condition Image Study", "internal_name": "skin-condition-pilot-v1", "description": "

We're collecting images of minor skin conditions to help train medical AI systems.

", "estimated_completion_time": 10, "maximum_allowed_time": 30, "reward": 500, "total_available_places": 100, "data_collection_method": "AI_TASK_BUILDER_COLLECTION", "data_collection_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b" } ``` Then publish the study: ```bash POST /api/v1/studies/{study_id}/transition/ ``` ```json { "action": "PUBLISH" } ``` ## Retrieving responses After participants have completed your study, you can retrieve their submitted data as a ZIP archive containing all responses and uploaded files. See [Exporting Collection Data](/api-reference/task-builder/exporting-collection-data) for the full guide. --- By using Task Builder, you agree to our [Task Builder Terms](https://prolific.notion.site/Researcher-Terms-7787f102f0c541bdbe2c04b5d3285acb).