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

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 }

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.

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

Example

1 {
2   "type": "file_upload",
3   "description": "Upload a photo of the item",
4   "order": 3
5 }