API ReferenceAI Task Builder

Working with Collections

View as MarkdownOpen in ClaudeOpen in ChatGPT

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

1

Create a collection: Define your collection structure including pages, instructions, and content blocks in a single request.

2

Update the collection (optional): Modify pages, instructions, or configuration as needed.

3

Create a study: Create a Prolific study that references your collection.

4

Publish the study: Make the study available to participants.

5

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.

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

1{
2  "name": "Skin Condition Image Collection",
3  "description": "Collecting images of minor skin conditions for medical AI training",
4  "task_details": {
5    "task_name": "Skin Condition Photo Submission",
6    "task_introduction": "<p>Help us build a medical imaging dataset by submitting photos of minor skin conditions.</p>",
7    "task_steps": "<ol><li>Review the consent information</li><li>Answer questions about yourself</li><li>Upload a clear photo of the affected area</li></ol>"
8  },
9  "collection_items": [
10    {
11      "order": 1,
12      "title": "About You",
13      "page_items": [
14        {
15          "order": 1,
16          "type": "multiple_choice",
17          "description": "What is your skin type?",
18          "answer_limit": 1,
19          "options": [
20            { "label": "Type I - Very fair", "value": "type_1" },
21            { "label": "Type II - Fair", "value": "type_2" },
22            { "label": "Type III - Medium", "value": "type_3" },
23            { "label": "Type IV - Olive", "value": "type_4" },
24            { "label": "Type V - Brown", "value": "type_5" },
25            { "label": "Type VI - Dark", "value": "type_6" }
26          ]
27        },
28        {
29          "order": 2,
30          "type": "multiple_choice",
31          "description": "What is your age range?",
32          "answer_limit": 1,
33          "options": [
34            { "label": "18-24", "value": "18-24" },
35            { "label": "25-34", "value": "25-34" },
36            { "label": "35-44", "value": "35-44" },
37            { "label": "45-54", "value": "45-54" },
38            { "label": "55-64", "value": "55-64" },
39            { "label": "65+", "value": "65+" }
40          ]
41        }
42      ]
43    },
44    {
45      "order": 2,
46      "title": "Image Submission",
47      "page_items": [
48        {
49          "order": 1,
50          "type": "rich_text",
51          "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible."
52        },
53        {
54          "order": 2,
55          "type": "image",
56          "url": "https://example.com/assets/photo-guidelines.png",
57          "alt_text": "Example of a well-lit, in-focus photograph"
58        },
59        {
60          "order": 3,
61          "type": "free_text",
62          "description": "Briefly describe the skin condition shown in your image"
63        },
64        {
65          "order": 4,
66          "type": "file_upload",
67          "description": "Upload a clear photo of the affected area"
68        }
69      ]
70    }
71  ]
72}

Task details

The optional task_details object provides context to participants:

FieldTypeDescription
task_namestringTitle displayed to participants
task_introductionstringIntroduction or general guidance
task_stepsstringSteps 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

TypeDescription
multiple_choiceSelection 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_textOpen-ended text input
multiple_choice_with_free_textSelection from options, each with a heading and an associated free text field for additional input
file_uploadFile submission (images, documents, etc.)

Instruction fields

All instructions require a description field containing the prompt or question text.

Multiple choice:

1{
2  "order": 1,
3  "type": "multiple_choice",
4  "description": "What is your skin type?",
5  "answer_limit": 1,
6  "options": [
7    { "label": "Type I - Very fair", "value": "type_1" },
8    { "label": "Type II - Fair", "value": "type_2" },
9    { "label": "Type III - Medium", "value": "type_3" }
10  ]
11}

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 for full details.

Multiple choice with free text:

1{
2  "order": 1,
3  "type": "multiple_choice_with_free_text",
4  "description": "Rate the following aspects of the image:",
5  "answer_limit": -1,
6  "options": [
7    { "label": "Good", "value": "lighting_good", "heading": "Lighting" },
8    { "label": "Good", "value": "focus_good", "heading": "Focus" },
9    { "label": "Good", "value": "framing_good", "heading": "Framing" }
10  ]
11}

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:

1{
2  "order": 1,
3  "type": "free_text",
4  "description": "Describe the affected area in your own words",
5  "placeholder_text_input": "e.g. Small red patch on left forearm..."
6}

The optional placeholder_text_input field provides hint text displayed in the input field before the participant enters their response.

Content block types

TypeDescription
imageDisplay an image with alt text and optional caption
rich_textFormatted text content (Markdown supported)

Content block schemas

Image content block:

1{
2  "order": 1,
3  "type": "image",
4  "url": "https://example.com/reference-image.png",
5  "alt_text": "Description of the image for accessibility",
6  "caption": "Optional caption displayed below the image"
7}

The url must use HTTPS. The alt_text field is required for accessibility; caption is optional.

Rich text content block:

1{
2  "order": 1,
3  "type": "rich_text",
4  "content": "Instructions with **bold** and *italic* formatting."
5}

The content field supports Markdown formatting.

Response

A successful request returns the created collection with IDs assigned to the collection, pages, and page items:

1{
2  "id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
3  "name": "Skin Condition Image Collection",
4  "description": "Collecting images of minor skin conditions for medical AI training",
5  "status": "draft",
6  "collection_items": [
7    {
8      "id": "0192a3b4-d6e7-7f8a-0b1c-2d3e4f5a6b7c",
9      "order": 1,
10      "title": "About You",
11      "page_items": [
12        {
13          "id": "0192a3b4-e7f8-7a0b-1c2d-3e4f5a6b7c8d",
14          "order": 1,
15          "type": "multiple_choice",
16          "description": "What is your skin type?",
17          "answer_limit": 1,
18          "options": [
19            { "label": "Type I - Very fair", "value": "type_1" },
20            { "label": "Type II - Fair", "value": "type_2" },
21            { "label": "Type III - Medium", "value": "type_3" },
22            { "label": "Type IV - Olive", "value": "type_4" },
23            { "label": "Type V - Brown", "value": "type_5" },
24            { "label": "Type VI - Dark", "value": "type_6" }
25          ]
26        },
27        {
28          "id": "0192a3b4-f8a9-7b0c-1d2e-4f5a6b7c8d9e",
29          "order": 2,
30          "type": "multiple_choice",
31          "description": "What is your age range?",
32          "answer_limit": 1,
33          "options": [
34            { "label": "18-24", "value": "18-24" },
35            { "label": "25-34", "value": "25-34" },
36            { "label": "35-44", "value": "35-44" },
37            { "label": "45-54", "value": "45-54" },
38            { "label": "55-64", "value": "55-64" },
39            { "label": "65+", "value": "65+" }
40          ]
41        }
42      ]
43    },
44    {
45      "id": "0192a3b5-a9b0-7c1d-2e3f-5a6b7c8d9e0f",
46      "order": 2,
47      "title": "Image Submission",
48      "page_items": [
49        {
50          "id": "0192a3b5-b0c1-7d2e-3f4a-6b7c8d9e0f1a",
51          "order": 1,
52          "type": "rich_text",
53          "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible."
54        },
55        {
56          "id": "0192a3b5-c1d2-7e3f-4a5b-7c8d9e0f1a2b",
57          "order": 2,
58          "type": "image",
59          "url": "https://example.com/assets/photo-guidelines.png",
60          "alt_text": "Example of a well-lit, in-focus photograph"
61        },
62        {
63          "id": "0192a3b5-d2e3-7f4a-5b6c-8d9e0f1a2b3c",
64          "order": 3,
65          "type": "free_text",
66          "description": "Briefly describe the skin condition shown in your image"
67        },
68        {
69          "id": "0192a3b5-e3f4-7a5b-6c7d-9e0f1a2b3c4d",
70          "order": 4,
71          "type": "file_upload",
72          "description": "Upload a clear photo of the affected area"
73        }
74      ]
75    }
76  ]
77}

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.

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

1{
2  "name": "Skin Condition Image Collection",
3  "description": "Collecting images of minor skin conditions for medical AI training",
4  "task_details": {
5    "task_name": "Skin Condition Photo Submission",
6    "task_introduction": "<p>Help us build a medical imaging dataset by submitting photos of minor skin conditions.</p>",
7    "task_steps": "<ol><li>Review the consent information</li><li>Answer questions about yourself</li><li>Upload a clear photo of the affected area</li></ol>"
8  },
9  "collection_items": [
10    {
11      "order": 1,
12      "title": "Consent",
13      "page_items": [
14        {
15          "order": 1,
16          "type": "rich_text",
17          "content": "Before participating, please review and acknowledge the following:"
18        },
19        {
20          "order": 2,
21          "type": "multiple_choice",
22          "description": "Please confirm all of the following:",
23          "answer_limit": 3,
24          "options": [
25            { "label": "I understand my images may be used for AI training purposes", "value": "consent_ai_training" },
26            { "label": "I confirm I am over 18 years of age", "value": "consent_age" },
27            { "label": "I consent to participate in this study", "value": "consent_participate" }
28          ]
29        }
30      ]
31    },
32    {
33      "order": 2,
34      "title": "About You",
35      "page_items": [
36        {
37          "order": 1,
38          "type": "multiple_choice",
39          "description": "What is your skin type?",
40          "answer_limit": 1,
41          "options": [
42            { "label": "Type I - Very fair", "value": "type_1" },
43            { "label": "Type II - Fair", "value": "type_2" },
44            { "label": "Type III - Medium", "value": "type_3" },
45            { "label": "Type IV - Olive", "value": "type_4" },
46            { "label": "Type V - Brown", "value": "type_5" },
47            { "label": "Type VI - Dark", "value": "type_6" }
48          ]
49        },
50        {
51          "order": 2,
52          "type": "multiple_choice",
53          "description": "What is your age range?",
54          "answer_limit": 1,
55          "options": [
56            { "label": "18-24", "value": "18-24" },
57            { "label": "25-34", "value": "25-34" },
58            { "label": "35-44", "value": "35-44" },
59            { "label": "45-54", "value": "45-54" },
60            { "label": "55-64", "value": "55-64" },
61            { "label": "65+", "value": "65+" }
62          ]
63        }
64      ]
65    },
66    {
67      "order": 3,
68      "title": "Image Submission",
69      "page_items": [
70        {
71          "order": 1,
72          "type": "rich_text",
73          "content": "Please ensure your photo is **well-lit** and in focus. The affected area should be clearly visible."
74        },
75        {
76          "order": 2,
77          "type": "image",
78          "url": "https://example.com/assets/photo-guidelines.png",
79          "alt_text": "Example of a well-lit, in-focus photograph"
80        },
81        {
82          "order": 3,
83          "type": "free_text",
84          "description": "Briefly describe the skin condition shown in your image"
85        },
86        {
87          "order": 4,
88          "type": "file_upload",
89          "description": "Upload a clear photo of the affected area"
90        }
91      ]
92    }
93  ]
94}

Publishing a collection

To make your collection available to participants, create a Prolific study that references it.

$POST /api/v1/studies/

When creating the study, set data_collection_method to AI_TASK_BUILDER_COLLECTION and provide your collection ID:

1{
2  "name": "Skin Condition Image Study",
3  "internal_name": "skin-condition-pilot-v1",
4  "description": "<p>We're collecting images of minor skin conditions to help train medical AI systems.</p>",
5  "estimated_completion_time": 10,
6  "maximum_allowed_time": 30,
7  "reward": 500,
8  "total_available_places": 100,
9  "data_collection_method": "AI_TASK_BUILDER_COLLECTION",
10  "data_collection_id": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
11}

Then publish the study:

$POST /api/v1/studies/{study_id}/transition/
1{
2  "action": "PUBLISH"
3}

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.