# Collections # Working with Collections **Early Access** AI Task Builder Collections are an early-access feature that may be enabled on your workspace upon request. To request access or contribute towards the feature's roadmap, visit our help center at [https://researcher-help.prolific.com/en/](https://researcher-help.prolific.com/en/) and drop us a message in the chat. Your activation request will be reviewed by our team. Note: This feature is under active development and you may encounter bugs. An AI 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, "title": "About You", "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, "title": "Image Submission", "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 | | `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 (images, documents, etc.) | #### 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). 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/ai-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. #### Content block types | Type | Description | | ----------- | --------------------------------------------------- | | `image` | Display an image with alt text and optional caption | | `rich_text` | Formatted text content (Markdown supported) | ### 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 supports Markdown formatting. ### 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, "title": "About You", "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, "title": "Image Submission", "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. 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, "title": "Consent", "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, "title": "About You", "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, "title": "Image Submission", "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 via the responses endpoint. The researcher-facing responses endpoint is coming soon. Check back for updates on retrieving collection data. *** By using AI Task Builder, you agree to our [AI Task Builder Terms](https://prolific.notion.site/Researcher-Terms-7787f102f0c541bdbe2c04b5d3285acb).