Create Poll

When building a poll you can add:

SingleChoice and MultipleChoice questions
Other question formats: Likert/Matrix, Order, Upvote, NetPromoterScore, RateIt, Swiper, Reaction, TextEntry, TierList, and ThisOrThat
A QuestionBank block that draws its questions from a question bank instead of carrying them itself
Form fields
General blocks
One result page

Properties every poll question shares

Unless a question type is listed as an exception below, all poll question blocks accept these:

Property	Required	Type	Description	Default
`title`	✓	string	The question
`description`		string	The description of the question
`media`		string\|object	An image, video, or social media embed shown with the question. Adding it automatically switches its display on. See Use media
`mediaOrientation`		string	How that media is cropped: `Settings`, `Wide`, `Square`, `Tall`, or `Original`. `Settings` inherits the Riddle-wide setting	Settings
`isRequired`		boolean	If set to `false`, the user can skip the question	true

Every question type supports a slightly different subset - the per-type tables below are exhaustive. A property a question type does not support is ignored rather than applied, so if a setting does not show up in the Riddle, check the table for that type first. The one exception is otherOption, which is rejected outright when sent to a question type without an "Other" answer.

Every collection on this page - items, a Likert scale, a TierList's tiers - follows the shared item formats: an array of objects, the entry's text in its title. In a poll an item object is:

Item property	Required	Type	Description
`title`	✓	string	The item text
`description`		string	A secondary line under the item
`media`		string\|object	An image or video for this individual item

A question can hold at most 100 items, and a whole build may reference at most 15 media files.

Add Single/multiple choice questions

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `SingleChoice` or `MultipleChoice`
`title`	✓	string	The question
`items`	✓	object	2-100 possible choices, each an object with its `title` plus an optional description or media - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`itemsShuffled`		boolean	If set to `true`, the order of the items/choices will be shuffled	false
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`layoutType`		string	The layout of the items, either `Rows` or `Columns`	Rows
`canWrapItems`		boolean	Whether items may wrap onto a new line	true
`isHeightFlexible`		boolean	Whether each item's height flexes with its content	true
`otherOption`		object	Adds an "Other" answer with a free-text entry the user fills in: `{"isEnabled": boolean, "label": string}`. Both keys are optional and independent of each other	`isEnabled` false, `label` "Other"
`answerMediaOrientation`		string	How the media of the individual answer items is cropped: `Settings`, `Wide`, `Square`, `Tall`, `Original`	Wide
`isDescriptionVisible`		boolean	Whether the per-answer descriptions are shown. One shared flag for the whole question, not one per answer: giving any item a `description` switches it on, sending `false` keeps the descriptions stored but hidden	derived from the items
`maxSelections`		integer	`MultipleChoice` only: how many options may be picked at most (1-100)	2
`hasUnlimitedSelections`		boolean	`MultipleChoice` only: lift the `maxSelections` cap entirely	true
`areRemainingVotesVisible`		boolean	`MultipleChoice` only: show the user how many selections are left	true

Example

{
    "title": "The best noodles?",
    "type": "SingleChoice",
    "items": [
        { "title": "Spaghetti" },
        { "title": "Fusilli" }
    ]
}

Here the difference between SingleChoice and MultipleChoice is that with SingleChoice the user can only select one answer, while with MultipleChoice the user can select multiple answers. Apart from that, they are the same for the build configuration - except for the three selection-cap properties above, which only a MultipleChoice question has.

Note: otherOption only exists on SingleChoice and MultipleChoice; sending it on any other poll question type is rejected with a validation error. It must be an object; Its two keys are independent of each other: label renames the "Other" answer but does not add it, and isEnabled on its own adds it with the default label "Other". Set both to add a renamed one:

{
    "otherOption": {
        "isEnabled": true,
        "label": "Something else"
    }
}

An example using all properties:

{
    "title": "Which toppings do you want?",
    "type": "MultipleChoice",
    "media": "https://httpbin.io/image/jpeg",
    "items": [
        { "title": "Cheese" },
        { "title": "Pineapple" },
        { "title": "Mushrooms" }
    ],
    "itemsShuffled": true,
    "layoutType": "Columns",
    "maxSelections": 2,
    "hasUnlimitedSelections": false,
    "areRemainingVotesVisible": true,
    "otherOption": {
        "isEnabled": true,
        "label": "Something else"
    }
}

Add Likert / matrix question

A matrix question allows you to ask a question with multiple items and a scale. The user can select one answer for each item.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `Matrix`
`title`	✓	string	The question
`items`	✓	object	The statements (the matrix rows), each an object with its `title` - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`itemsShuffled`		boolean	If set to `true`, the order of the items/statements will be shuffled	false
`scale`		object\|object	The scale the user can choose from, e.g. 'Bad', 'Medium', 'Good' (2-100 entries). Each entry is an object with its `title`; key the collection by the value a rating stands for if you do not want the default 0, 1, 2, ... - see item formats	5 scale items from 'Strongly agree' to 'Strongly disagree', plus 'N/A'
`isNaEnabled`		boolean	If set to `true`, the user can select 'Not applicable' for each item	false
`isSingleChoiceEnabled`		boolean	If set to `true`, the user can select only one answer per item	true
`isMobileViewEnabled`		boolean	Whether the dedicated, stacked mobile layout is used	true
`isRequired`		boolean	If set to `false`, the user can skip the question	true

Note: A matrix question renders as a grid rather than a list of answers, so it does not have layoutType, canWrapItems, isHeightFlexible, otherOption, answerMediaOrientation, maxSelections, hasUnlimitedSelections or areRemainingVotesVisible either - sending one is ignored like any other unsupported property, or rejected outright with strictProperties: true (see Getting started). Its items and scale entries carry no description or media of their own either - only their title (plus, for scale, the custom scoring value as the entry's key). It does support isRequired, media and mediaOrientation for the question itself, like every other question.

Example

Here is an example with only the required configuration properties:

{
    "title": "I am happy with the following aspects of Riddle.",
    "description": "Choose one from 'Strongly agree' to 'Strongly disagree'",
    "type": "Matrix",
    "items": [
        { "title": "Design" },
        { "title": "Usability" },
        { "title": "Performance" }
    ]
}

For the next example we additionally shuffle the items, customize the scale (and its values) and set the other flags.

{
    "title": "I am happy with the following aspects of Riddle.",
    "description": "Choose one from 'Bad' to 'Good'",
    "type": "Matrix",
    "items": [
        { "title": "Design" },
        { "title": "Usability" },
        { "title": "Performance" }
    ],
    "itemsShuffled": true,
    "scale": {
        "0": { "title": "Bad" },
        "2": { "title": "Medium" },
        "4": { "title": "Good" }
    },
    "isNaEnabled": true,
    "isSingleChoiceEnabled": false
}

As you can see in the above example, scale can be keyed by the value that will be saved in the database (e.g. the user selects Bad => scale value 0 is saved as the response). By default the scale values are a series of auto incremented integers: send scale as a plain array to get them, e.g. {"scale": [{"title": "Bad"}, {"title": "Medium"}, {"title": "Good"}]}.

Add order it question

An order it question allows you to ask a question with multiple items and the user can drag and drop them into the order they prefer.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `Order`
`title`	✓	string	The question
`items`	✓	object	2-100 items to rank, each an object with its `title` plus an optional description or media - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`itemsShuffled`		boolean	If set to `true`, the order of the items is shuffled before the user ranks them	false
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`layoutType`		string	The layout of the items, either `Rows` or `Columns`	Rows
`rankFormat`		string	How the ranks of the items are displayed, either `Number`, `Letter` or `NumberEnum`. Supplying it also switches the rank display on	Number
`isRankFormatEnabled`		boolean	Explicitly switch the rank display on/off. Setting `rankFormat` already switches it on; use `isRankFormatEnabled: false` to disable it again while keeping the format configured
`isReverseOrder`		boolean	Count the rank labels down from the highest number instead of up from 1. Purely a label concern - it does not change the user's actual ordering	false
`upDownButtons`		boolean	If set to `true`, up and down buttons are shown on desktop instead of drag and drop	true
`answerMediaOrientation`		string	How the media of the individual items is cropped	Wide
`isDescriptionVisible`		boolean	Whether the per-answer descriptions are shown. One shared flag for the whole question, not one per answer: giving any item a `description` switches it on, sending `false` keeps the descriptions stored but hidden	derived from the items

Note: An order question has no canWrapItems, isHeightFlexible or otherOption.

Example

{
    "title": "What are your favorite animals?",
    "description": "Drag and drop the items into the order you prefer",
    "type": "Order",
    "items": [
        { "title": "Dog" },
        { "title": "Cat" },
        { "title": "Bird" },
        { "title": "Fish" }
    ],
    "layoutType": "Rows",
    "rankFormat": "Number",
    "isReverseOrder": false,
    "upDownButtons": false
}

Add upvote question

An upvote question allows you to ask a question with multiple items and the user can select one or more items to upvote.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `Upvote`
`title`	✓	string	The question
`items`	✓	object	2-100 possible choices, each an object with its `title` - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`maxVotes`		integer	The maximum number of items the user can upvote	1
`areRemainingVotesVisible`		boolean	Show the user how many upvotes they have left	true
`isUpvoteSorted`		boolean	Re-order the items by their upvote count (most upvoted first)	true
`answerMediaOrientation`		string	How the media of the individual items is cropped	Wide
`isDescriptionVisible`		boolean	Whether the per-answer descriptions are shown. One shared flag for the whole question, not one per answer: giving any item a `description` switches it on, sending `false` keeps the descriptions stored but hidden	derived from the items

Note: An upvote question renders as a plain vote list, so it has no layoutType, canWrapItems or isHeightFlexible.

Example

{
    "title": "What do you like most about Riddle?",
    "description": "Select one or more items",
    "type": "Upvote",
    "items": [
        { "title": "Design" },
        { "title": "Usability" },
        { "title": "Performance" }
    ],
    "maxVotes": 2,
    "isUpvoteSorted": true,
    "areRemainingVotesVisible": true
}

Add Net Promoter Score question

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `NetPromoterScore`
`title`	✓	string	The question
`positiveTitle`	✓	string	The title of the positive score, e.g. `I completely agree`
`negativeTitle`	✓	string	The title of the negative score, e.g. `I completely disagree`
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`isRequired`		boolean	If set to `false`, the user can skip the question	true

Note: An NPS question always shows the fixed 0-10 scale, so it has no items and no layout properties (layoutType, canWrapItems, isHeightFlexible).

Example

{
    "title": "How likely are you to recommend Riddle to a friend?",
    "description": "Select one of the options below",
    "type": "NetPromoterScore",
    "positiveTitle": "I completely agree",
    "negativeTitle": "I completely disagree"
}

Add Rate It question

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `RateIt`
`title`	✓	string	The question
`items`	✓	object	2-100 things to rate, each an object with its `title` plus an optional description or media - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`itemsShuffled`		boolean	If set to `true`, the order of the items is shuffled	false
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`layoutType`		string	The layout of the items, either `Rows` or `Columns`	Columns
`canWrapItems`		boolean	Whether items may wrap onto a new line	true
`isHeightFlexible`		boolean	Whether each item's height flexes with its content	true
`displayType`		string	The display type of the rating, either `Stars` or `Numbers`	Stars
`starCount`		integer	The number of stars to display (if `displayType` is `Stars`); allowed range 1-10	5
`numberMin`		integer	The lowest number to display (if `displayType` is `Numbers`); allowed range -10 to 10	1
`numberMax`		integer	The highest number to display (if `displayType` is `Numbers`); allowed range -10 to 10	10
`isRateItSortedAfterVote`		boolean	Re-sort the rated items once a vote is in	false
`answerMediaOrientation`		string	How the media of the individual items is cropped	Wide
`isDescriptionVisible`		boolean	Whether the per-answer descriptions are shown. One shared flag for the whole question, not one per answer: giving any item a `description` switches it on, sending `false` keeps the descriptions stored but hidden	derived from the items

Note: starCount and numberMin/numberMax are mutually exclusive. If displayType is set to Stars, you cannot set numberMin or numberMax. If displayType is set to Numbers, you cannot set starCount. Setting the properties for the wrong displayType will throw a validation error.

Example

{
    "title": "How would you rate Riddle?",
    "type": "RateIt",
    "items": [
        { "title": "Design" },
        { "title": "Usability" },
        { "title": "Performance" }
    ],
    "itemsShuffled": true,
    "displayType": "Numbers",
    "numberMin": 1,
    "numberMax": 5
}

Add Swiper question

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `Swiper`
`title`	✓	string	The question
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`items`		object	Exactly two swiper items (FIRST: negative, SECOND: positive); described in detail below. The item's text is its `title` - see item formats	the two default Riddle swipe buttons
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`textPosition`		string	Where the item text sits relative to the card: `BelowCard` or `Overlay`	BelowCard
`buttonType`		string	The look of the two swipe buttons: `Riddle`, `Emoji`, `Media` or `Text`. Set it after `items` if you want to override what the item contents imply	Riddle
`colorLikeButtonBackground`		string	The background color of the like button	#59e1abff
`colorLikeButtonIcon`		string	The color of the like button icon	#000000ff
`colorLikeButtonText`		string	The color of the like button text	#000000ff
`colorDislikeButtonBackground`		string	The background color of the dislike button	#000000ff
`colorDislikeButtonIcon`		string	The color of the dislike button icon	#ffffff
`colorDislikeButtonText`		string	The color of the dislike button text	#ffffff

Specifying negative / positive items

If you want to specify the negative / positive items in more detail, pass two objects in the items array. Each of them has the following properties:

Property	Type	Description
`title`	string	The title of the item
`emoji`	string	The emoji to display in the item, e.g. `👍` or `👎`
`media`	string\|object	The image or video to display in the item

Note: Each item needs exactly one of title, emoji, and media - an item is either a text card, an emoji card or a media card. Sending an item with none of them, or with more than one of them, is rejected with a validation error.

Example

{
    "title": "How do you feel about Riddle?",
    "description": "Swipe left or right to answer",
    "type": "Swiper",
    "items": [
        {
            "emoji": "😞"
        },
        {
            "emoji": "😍"
        }
    ],
    "textPosition": "Overlay",
    "buttonType": "Emoji"
}

Add Reaction Poll question

A reaction poll allows users to react to a question using a scale, e.g. from 'strongly disagree' to 'strongly agree'.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `Reaction`
`title`	✓	string	The question
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`reactionType`		string	One of the built-in scales: `AgreeDisagree` or `LikeDislike`
`reactionScale`		string[]	A custom scale, lowest to highest, e.g. "Bad", "Okay", "Good"
`isRequired`		boolean	If set to `false`, the user can skip the question	true

Note: You need exactly one of reactionType and reactionScale. Leaving both out is rejected (PollReactionBlock must have either "reactionType" or "reactionScale" set.), and so is setting both (PollReactionBlock cannot have a "reactionType" set when "reactionScale" is defined.) - neither silently wins over the other.

Note: A custom reactionScale must contain at least 3 items and an odd number of items - an even number of items will be rejected. The scale is scored symmetrically around 0, so ["Bad", "Okay", "Good"] stores the scores -1, 0 and 1.

Example: predefined reaction scale

{
    "title": "How do you feel about Riddle?",
    "description": "Select one of the options below",
    "type": "Reaction",
    "reactionType": "AgreeDisagree"
}

Example: custom reaction scale

{
    "title": "How do you feel about Riddle?",
    "description": "Select one of the options below",
    "type": "Reaction",
    "reactionScale": [
        "Bad",
        "Okay",
        "Good"
    ]
}

Add TextEntry question

A free-text question: the person taking the Poll can type anything, there is no correct answer.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `TextEntry`
`title`	✓	string	The question
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`label`		string	A label shown above the text input
`inputDescription`		string	A description shown with the text input
`placeholder`		string	Placeholder text shown inside the empty input
`prefilledText`		string	Prefilled value for the input
`isAnswerRequired`		boolean	Whether the text input itself must be filled in before the respondent can continue	false
`requiredMessage`		string	Message shown when the input is required but left empty. Only allowed together with `isAnswerRequired: true`
`maxLength`		integer	Maximum number of characters accepted (>= 0)
`regex`		string	Regex to validate the input; setting it also switches advanced validation on
`validationMessage`		string	Message shown when the regex validation fails. Only allowed together with `regex`
`isAdvancedValidationEnabled`		boolean	Explicitly switch length/regex validation on/off. Setting `regex` or `validationMessage` already switches it on; use `isAdvancedValidationEnabled: false` to disable it again while keeping `regex` configured

Note: There are genuinely two independent "required" flags on this question type: isRequired (shared with every other poll question - can the respondent skip the whole question) and isAnswerRequired (specific to TextEntry - once the respondent engages with the question, must the text field itself be filled in). They default differently (isRequired defaults true, isAnswerRequired defaults false) and neither implies the other.

Example

{
    "title": "What's your favorite noodle dish?",
    "type": "TextEntry",
    "placeholder": "e.g. Spaghetti Carbonara",
    "isAnswerRequired": true,
    "requiredMessage": "Please tell us your favorite dish",
    "regex": "^[A-Za-z ]+$",
    "validationMessage": "Please only use letters and spaces"
}

Add TierList question

A drag-and-drop ranking question: the person taking the Poll sorts a list of items into named tiers (e.g. "S"/"A"/"B"/"C"/"D"/"F").

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `TierList`
`title`	✓	string	The question
`tiers`	✓	object	At least 2 tiers, in order; see below. The tier label is its `title` - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`items`		object	The items to sort into tiers, at least 1 if the key is sent at all. May start empty and be added later. The item text is its `title` - see item formats
`isItemTitleEnabled`		boolean	Explicitly switch the display of each item's title on/off. Giving any item a `title` already switches it on - see below	true
`isItemMediaEnabled`		boolean	Explicitly switch the display of each item's media on/off. Giving any item a `media` already switches it on - see below	true
`itemMediaOrientation`		string	How each item's own media is cropped: `Settings`, `Wide`, `Square`, `Tall`, or `Original`	Settings

Each entry in tiers supports:

Property	Required	Type	Description
`title`	✓	string	The name of the tier, e.g. "S"
`colorBg`		string	Background color of the tier
`colorText`		string	Text color of the tier

Each entry in items supports:

Property	Required	Type	Description	Default
`title`		string	The item's label
`media`		string\|object	An image or video for this item

Note: Giving any item a title (even an empty string) or a media switches the corresponding shared display flag (isItemTitleEnabled/isItemMediaEnabled) on for the whole question. Both default to true already, so this only matters if you had previously switched one off and now add new item content - an explicit isItemTitleEnabled/isItemMediaEnabled in the same build always wins over the automatic switch-on.

Example

{
    "title": "Rank these noodle dishes",
    "type": "TierList",
    "tiers": [
        { "title": "S" },
        { "title": "A" },
        { "title": "B" },
        { "title": "F" }
    ],
    "items": [
        { "title": "Spaghetti Carbonara" },
        { "title": "Fusilli Pesto" },
        { "title": "Instant noodles" }
    ]
}

Add This or That question

A head-to-head comparison: the person taking the Poll is shown two contenders at a time and picks one, until every pair has been decided.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `ThisOrThat`
`title`	✓	string	The question
`items`	✓	object	The contenders - one flat list of at least 2, never a list of pairs. The pairs are formed from this list positionally, so the order decides who competes against whom. Each contender is an object with its `title` - see item formats
`description`		string	The description of the question
`media`		string\|object	Media to display with the question
`isRequired`		boolean	If set to `false`, the user can skip the question	true
`isProgressbarEnabled`		boolean	Show a progress bar counting the decided pairs	false
`isItemTitleEnabled`		boolean	Explicitly switch the display of each contender's title on/off. Giving any contender a `title` already switches it on - see below	true
`isItemMediaEnabled`		boolean	Explicitly switch the display of each contender's media on/off. Giving any contender a `media` already switches it on - see below	true
`itemMediaOrientation`		string	How each contender's own media is cropped: `Settings`, `Wide`, `Square`, `Tall`, or `Original`	Square
`separator`		string	What is shown between the two contenders: `Versus`, `Colon`, `At`, `Dash`, `Slash`, or `X`	Versus

Each entry in items supports:

Property	Required	Type	Description	Default
`title`		string	The contender's label
`media`		string\|object	An image or video for this contender

Each contender needs a title, a media, or both - a contender with neither is a blank half of a comparison and is rejected.

Note: Giving any contender a title (even an empty string) or a media switches the corresponding shared display flag (isItemTitleEnabled/isItemMediaEnabled) on for the whole question. Both default to true already, so this only matters if you had previously switched one off and now add new contender content - an explicit isItemTitleEnabled/isItemMediaEnabled in the same build always wins over the automatic switch-on.

Example

{
    "title": "Which one do you prefer?",
    "type": "ThisOrThat",
    "separator": "Versus",
    "isProgressbarEnabled": true,
    "items": [
        { "title": "Cats" },
        { "title": "Dogs" },
        { "title": "Hamsters" },
        { "title": "Fish" }
    ]
}

Add a Question Bank block

A QuestionBank block has no questions of its own: it draws them from a question bank - a reusable pool of questions managed outside the Riddle - when the Riddle is viewed. The build configuration only references the bank by its ID; it never creates or edits the bank's questions.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `QuestionBank`
`questionBankId`	✓	integer	The ID of an existing question bank whose `riddleType` is `Poll`. A bank built for a Quiz, a bank of a different project, or an ID that does not exist is rejected
`title`		string	A plain-text label for the block (no HTML)
`isRequired`		boolean	Whether the drawn question has to be answered before continuing	true
`randomizationType`		string	`TimeBased` re-draws the questions every `refreshInterval` hours, `None` draws once and leaves the selection fixed	TimeBased
`refreshInterval`		integer	How often the draw is refreshed, in hours (minimum `1`). Only meaningful together with `randomizationType: "TimeBased"`	24
`questionBankBlocks`	✓	object	One entry per block type the bank should draw into, see below. At least one entry is required - a block with none draws nothing at all

The `questionBankBlocks` array

Each entry says which kind of question is drawn from the bank, and how it is filtered:

Property	Required	Type	Description	Default
`blockType`	✓	string	`SingleChoice`, `MultipleChoice`, `Reaction`, `Upvote`, `Order`, `Swiper`, `RateIt`, `Matrix`, or `NetPromoterScore`. Each block type may appear at most once
`isEnabled`		boolean	Whether this block type actually draws from the bank	false
`questionBankCriteria`		object	Filters for the draw, see below. Omitted or empty means no filter - every item of that block type is eligible

Each entry of questionBankCriteria:

Property	Required	Type	Description	Default
`category`	✓	string	A category of the bank's items. Must be unique within one `questionBankCriteria` array
`difficultyRange`		integer	Exactly two integers `[min, max]` between 1 and 10, `min` <= `max`. An empty array means no difficulty filter
`maxNumberOfQuestions`		integer	At most this many questions are drawn from that category. Omit it to compute a default automatically, never send an explicit `null`	computed automatically

Note: Omitting maxNumberOfQuestions computes a default of at most 5, and at least 1, based on how many published items in the bank match the category and difficultyRange. Sending an explicit null is rejected.

Note: The bank's inventory is not checked while building. Asking for more questions than the bank actually holds is reported as a warning when publishing, never as a build error - call GET /question-bank/riddle-items/{riddleUUID}/{blockId} to see which items a block would draw right now.

Note: A QuestionBank block always draws from the bank's published state. A bank with unpublished changes keeps serving its last published questions, so publish the bank after changing its items.

Note: Sending questionBankBlocks when editing an existing Riddle replaces the whole array, like every other repeating collection of the Builder API.

Example

{
    "type": "QuestionBank",
    "title": "Random question of the day",
    "questionBankId": 4712,
    "randomizationType": "TimeBased",
    "refreshInterval": 24,
    "questionBankBlocks": [
        {
            "blockType": "SingleChoice",
            "isEnabled": true,
            "questionBankCriteria": [
                {
                    "category": "Sports",
                    "difficultyRange": [1, 5],
                    "maxNumberOfQuestions": 3
                }
            ]
        }
    ]
}

Result page

In a poll only one result page is allowed which is specified in build.result. Basic results have a title and description property.

Example in build.result:

{
    "title": "Thank you!",
    "description": "We are happy to have you here"
}

If you want to create complex result pages with texts, images, answered blocks, ... click here to learn how to build advanced result pages.

Full example

Example with all available question types + options:

{
    "type": "Poll",
    "build": {
        "title": "Poll example (Builder API)",
        "blocks": [
            {
                "title": "What's your favorite color?",
                "type": "SingleChoice",
                "media": "https://httpbin.io/image/png",
                "mediaOrientation": "Wide",
                "items": [
                    { "title": "Red" },
                    {
                        "title": "Blue",
                        "description": "Like the sky",
                        "media": "https://httpbin.io/image/webp"
                    },
                    { "title": "Green" },
                    { "title": "Yellow" }
                ],
                "itemsShuffled": true,
                "layoutType": "Columns",
                "canWrapItems": true,
                "isHeightFlexible": true,
                "answerMediaOrientation": "Square",
                "otherOption": {
                    "isEnabled": true,
                    "label": "Something else"
                }
            },
            {
                "title": "What are your favorite animals?",
                "type": "MultipleChoice",
                "items": [
                    { "title": "Dog" },
                    { "title": "Cat" },
                    { "title": "Bird" },
                    { "title": "Fish" }
                ],
                "isRequired": false,
                "maxSelections": 2,
                "hasUnlimitedSelections": false,
                "areRemainingVotesVisible": true
            },
            {
                "title": "I am happy with the following aspects of Riddle.",
                "description": "Choose one from 'Bad' to 'Good'",
                "type": "Matrix",
                "items": [
                    { "title": "Design" },
                    { "title": "Usability" },
                    { "title": "Performance" }
                ],
                "itemsShuffled": true,
                "scale": {
                    "0": { "title": "Bad" },
                    "2": { "title": "Medium" },
                    "4": { "title": "Good" }
                },
                "isNaEnabled": true,
                "isSingleChoiceEnabled": false,
                "isMobileViewEnabled": true
            },
            {
                "title": "Rank these animals",
                "description": "Drag and drop the items into the order you prefer",
                "type": "Order",
                "items": [
                    { "title": "Dog" },
                    { "title": "Cat" },
                    { "title": "Bird" },
                    { "title": "Fish" }
                ],
                "itemsShuffled": true,
                "layoutType": "Rows",
                "rankFormat": "Number",
                "isReverseOrder": false,
                "upDownButtons": false,
                "answerMediaOrientation": "Wide"
            },
            {
                "title": "What do you like most about Riddle?",
                "description": "Select one or more items",
                "type": "Upvote",
                "items": [
                    { "title": "Design" },
                    { "title": "Usability" },
                    { "title": "Performance" }
                ],
                "maxVotes": 2,
                "isUpvoteSorted": true,
                "areRemainingVotesVisible": true
            },
            {
                "title": "How would you rate Riddle?",
                "type": "RateIt",
                "items": [
                    { "title": "Design" },
                    { "title": "Usability" },
                    { "title": "Performance" }
                ],
                "itemsShuffled": true,
                "layoutType": "Columns",
                "displayType": "Numbers",
                "numberMin": 1,
                "numberMax": 5,
                "isRateItSortedAfterVote": true
            },
            {
                "title": "How likely are you to recommend Riddle to a friend?",
                "description": "Select one of the options below",
                "type": "NetPromoterScore",
                "positiveTitle": "I completely agree",
                "negativeTitle": "I completely disagree"
            },
            {
                "title": "Hot or not: Riddle",
                "description": "Swipe left or right to answer",
                "type": "Swiper",
                "items": [
                    {
                        "emoji": "😞"
                    },
                    {
                        "emoji": "😍"
                    }
                ],
                "textPosition": "Overlay",
                "buttonType": "Emoji",
                "colorLikeButtonBackground": "#59e1abff",
                "colorDislikeButtonBackground": "#000000ff"
            },
            {
                "title": "How do you feel about Riddle?",
                "description": "Select one of the options below",
                "type": "Reaction",
                "reactionType": "AgreeDisagree"
            },
            {
                "title": "Anything else you would like to tell us?",
                "type": "TextEntry",
                "label": "Your feedback",
                "placeholder": "e.g. I love the TierList question",
                "isAnswerRequired": true,
                "requiredMessage": "Please leave us a short note",
                "maxLength": 500
            },
            {
                "title": "Rank these noodle dishes",
                "type": "TierList",
                "tiers": [
                    {
                        "title": "S",
                        "colorBg": "#59e1ab",
                        "colorText": "#000000"
                    },
                    {
                        "title": "A"
                    },
                    {
                        "title": "B"
                    },
                    {
                        "title": "F"
                    }
                ],
                "items": [
                    {
                        "title": "Spaghetti Carbonara"
                    },
                    {
                        "title": "Fusilli Pesto"
                    },
                    {
                        "title": "Instant noodles"
                    }
                ],
                "isItemTitleEnabled": true,
                "itemMediaOrientation": "Square"
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}

Next steps

Now that you know the basics of building a poll, you might want to learn how to:

Build RiddlesBuild Riddles in your projects - Build Riddles

Riddle Types And Other BlocksCreate Quiz - Build Riddles