Instructions | Prolific API

Instructions define what participants are asked to do in AI Task Builder. The same instruction types are available for both Batches and Collections.

For usage details, see Working with Batches or Working with Collections.

Common fields

All instructions share these fields:

Field	Type	Required	Description
`type`	string	Yes	The instruction type
`description`	string	Yes	The prompt or question displayed to participants
`order`	integer	Yes	Position of this instruction relative to others
`helper_text`	string	No	Additional guidance text displayed below the question
`placeholder_text_input`	string	No	Placeholder text displayed in the input field

Instruction types

AI Task Builder supports the following instruction types:

multiple_choice - Selection from a list of options
free_text - Open-ended text input
free_text_with_unit - Text input with unit selection (e.g., measurements, currency)
multiple_choice_with_free_text - Selection with associated free text fields
file_upload - File submission field

multiple_choice

A selection from a list of options. Use answer_limit to control single or multi-select behavior.

Field	Type	Required	Description
`type`	string	Yes	`"multiple_choice"`
`description`	string	Yes	The question or prompt
`order`	integer	Yes	Position in the sequence
`answer_limit`	integer	Yes	Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up to the total options.
`disable_dropdown`	boolean	No	When `true`, always renders checkbox/radio elements instead of a dropdown. Default: `false`
`options`	array	Yes	List of options (minimum 1)
`options[].label`	string	Yes	Display text shown to participants
`options[].value`	string, number, or boolean	Yes	Value returned in responses

By default, when there are 5 or more options, a dropdown select element is rendered instead of checkboxes or radio buttons. Set disable_dropdown: true to always use checkboxes (for multi-select) or radio buttons (for single-select) regardless of option count.

Example

1 {
2   "type": "multiple_choice",
3   "description": "What is the sentiment of this text?",
4   "order": 1,
5   "answer_limit": 1,
6   "options": [
7     { "label": "Positive", "value": "positive" },
8     { "label": "Neutral", "value": "neutral" },
9     { "label": "Negative", "value": "negative" }
10   ]
11 }

Multi-select example

1 {
2   "type": "multiple_choice",
3   "description": "Select all topics that apply:",
4   "order": 1,
5   "answer_limit": -1,
6   "options": [
7     { "label": "Product quality", "value": "quality" },
8     { "label": "Customer service", "value": "service" },
9     { "label": "Pricing", "value": "pricing" },
10     { "label": "Shipping", "value": "shipping" }
11   ]
12 }

free_text

An open-ended text input field.

Field	Type	Required	Description
`type`	string	Yes	`"free_text"`
`description`	string	Yes	The question or prompt
`order`	integer	Yes	Position in the sequence

Example

1 {
2   "type": "free_text",
3   "description": "Explain your reasoning for the rating above",
4   "order": 2,
5   "helper_text": "Be specific about what influenced your decision",
6   "placeholder_text_input": "e.g. The text contains positive language such as..."
7 }

free_text_with_unit

A text input field where participants provide a numeric or text value along with a unit selection (e.g., measurements in cm or inches, weights in kg or lbs). The unit selector can appear before (prefix) or after (suffix) the text input.

Field	Type	Required	Description
`type`	string	Yes	`"free_text_with_unit"`
`description`	string	Yes	The question or prompt
`order`	integer	Yes	Position in the sequence
`unit_options`	array	Yes	List of available units (minimum 2)
`unit_options[].label`	string	Yes	Display text shown to participants
`unit_options[].value`	string, number, or boolean	Yes	Value returned in responses
`unit_position`	string	Yes	Position of unit selector: `"prefix"` (before input) or `"suffix"` (after input)
`default_unit`	string	No	Default selected unit (must match a value from `unit_options`)

Example: Height measurement

1 {
2   "type": "free_text_with_unit",
3   "description": "What is your height?",
4   "order": 1,
5   "unit_options": [
6     { "label": "Centimeters", "value": "cm" },
7     { "label": "Inches", "value": "in" }
8   ],
9   "unit_position": "suffix",
10   "default_unit": "cm",
11   "placeholder_text_input": "Enter your height"
12 }

Example: Currency amount

1 {
2   "type": "free_text_with_unit",
3   "description": "What is your budget?",
4   "order": 1,
5   "unit_options": [
6     { "label": "$", "value": "usd" },
7     { "label": "£", "value": "gbp" },
8     { "label": "€", "value": "eur" }
9   ],
10   "unit_position": "prefix",
11   "default_unit": "usd",
12   "helper_text": "Enter the amount in your preferred currency"
13 }

multiple_choice_with_free_text

A selection from options, where each option has a heading and an associated free text field. Use this when you need participants to both select an option and provide additional context.

Field	Type	Required	Description
`type`	string	Yes	`"multiple_choice_with_free_text"`
`description`	string	Yes	The question or prompt
`order`	integer	Yes	Position in the sequence
`answer_limit`	integer	Yes	Number of options that can be selected. Use `1` for single-select, `-1` for unlimited, or any number up to the total options.
`disable_dropdown`	boolean	No	When `true`, always renders checkbox/radio elements instead of a dropdown. Default: `false`
`options`	array	Yes	List of options (minimum 1)
`options[].label`	string	Yes	Display text shown to participants
`options[].value`	string, number, or boolean	Yes	Value returned in responses
`options[].heading`	string	Yes	Section heading that groups this option

Example

1 {
2   "type": "multiple_choice_with_free_text",
3   "description": "Rate the following aspects and provide comments:",
4   "order": 1,
5   "answer_limit": -1,
6   "options": [
7     { "label": "Good", "value": "accuracy_good", "heading": "Accuracy" },
8     { "label": "Needs improvement", "value": "accuracy_poor", "heading": "Accuracy" },
9     { "label": "Good", "value": "clarity_good", "heading": "Clarity" },
10     { "label": "Needs improvement", "value": "clarity_poor", "heading": "Clarity" }
11   ]
12 }

In this example, options are grouped under “Accuracy” and “Clarity” headings. Each selection includes an associated free text field for the participant to elaborate.

file_upload

A file submission field for participants to upload images, documents, or other files. Useful for collecting photos, documents, screenshots, or any file-based data from participants.

Field	Type	Required	Description
`type`	string	Yes	`"file_upload"`
`description`	string	Yes	The prompt describing what to upload
`order`	integer	Yes	Position in the sequence
`accepted_file_types`	array of strings	No	File extensions to accept (e.g., `[".jpg", ".png", ".pdf"]`). Each extension must start with a dot. Minimum 1 extension if provided. Default: `[".jpg", ".jpeg", ".png", ".heic", ".heif"]`
`max_file_size_mb`	number	No	Maximum file size in megabytes per file. Must be a positive number. Default: `25`
`min_file_count`	integer	No	Minimum number of files required. Must be at least `1`. Default: `1`
`max_file_count`	integer	No	Maximum number of files allowed. Must be at least `1` and greater than or equal to `min_file_count`. Default: `10`

Validation rules:

All file type extensions must start with a dot (e.g., ".pdf", not "pdf")
max_file_size_mb must be a positive number
min_file_count must be at least 1
max_file_count must be greater than or equal to min_file_count
If you omit accepted_file_types, the instruction will only accept common image formats (JPG, PNG, HEIC, HEIF)

Example: Single image upload

1 {
2   "type": "file_upload",
3   "description": "Upload a clear photo of your receipt",
4   "order": 1,
5   "helper_text": "Make sure the receipt is fully visible and in focus",
6   "accepted_file_types": [".jpg", ".jpeg", ".png"],
7   "max_file_size_mb": 10,
8   "min_file_count": 1,
9   "max_file_count": 1
10 }

Example: Multiple document upload

1 {
2   "type": "file_upload",
3   "description": "Upload supporting documents",
4   "order": 2,
5   "helper_text": "You can upload between 2-5 documents in PDF or image format",
6   "accepted_file_types": [".pdf", ".jpg", ".jpeg", ".png"],
7   "max_file_size_mb": 25,
8   "min_file_count": 2,
9   "max_file_count": 5
10 }

Example: Flexible image collection

1 {
2   "type": "file_upload",
3   "description": "Upload photos of the product from different angles",
4   "order": 3,
5   "accepted_file_types": [".jpg", ".jpeg", ".png", ".heic", ".heif"],
6   "max_file_size_mb": 15,
7   "min_file_count": 3,
8   "max_file_count": 10
9 }