Create Quiz

When building a quiz you can add:

Quiz questions with answer explanations: SingleChoice, MultipleChoice, and TextEntry ("Type the answer")
Quiz question with items to order
Flashcard questions
Form fields
General blocks
Multiple result pages: segment users based on their score

Add single/multiple choice questions

Properties

Property	Required	Type	Description	Default
`title`	✓	string	title of the question
`type`	✓	string	set to `SingleChoice` or `MultipleChoice`
`items`	✓	object	key-value array, consisting of the question as the key and the value is a boolean value indicating if the answer is correct
`itemsShuffled`		boolean	If set to `true`, the order of the items/choices will be shuffled	false
`itemsRightOrWrong`		boolean	If set to `true`, the items will be shown as right or wrong	true
`score`		integer	The score the user gets for answering this question correctly	1
`explanation`		object	An explanation object for the correct answer; learn more
`wrongExplanation`		object	An explanation object for the incorrect answer; learn more
`layoutType`		string	The layout of the items, either `Rows` or `Columns`	`Rows`

Example object

{
    "title": "The best noodles?",
    "type": "SingleChoice",
    "items":  {
        "Spaghetti": true,
        "Fusilli": false
    }
}

In this example Spaghetti would be the correct choice.

Please note that only one answer option can be correct for SingleChoice questions. If you try to add more than one correct answer the API will return an error.

Want to set answer explanations or the score per item? Learn more

Add "Type the answer" questions

Properties

Property	Required	Type	Description	Default
`title`	✓	string	title of the block
`type`	✓	string	set to `TextEntry`
`answers`	✓	string[]	an array of possible answers
`ignoreCase`		boolean	set to true to ignore the case of the answer (e.g. "hello" and "Hello" would be considered the same)	false
`ignoreSpaces`		boolean	set to true to ignore spaces in the answer (e.g. "hello" and "h e l l o" would be considered the same)	false
`lives`		integer	set to a number to give the user multiple attempts to answer the question	1
`unlimitedLives`		boolean	set to true to give the user unlimited attempts to answer the question	false
`score`		integer	the score the user gets for answering this question correctly	1
`explanation`		object	An explanation object for the correct answer; learn more
`wrongExplanation`		object	An explanation object for the incorrect answer; learn more

Example object

{
    "title": "Type 'hello' in either Italian, German, or French.",
    "type": "TextEntry",
    "answers": ["Ciao", "Hallo", "Bonjour"]
}

Optional properties

By default the user must type the exact answer to get the question correct and only has one life/attempt. To change this behavior you can set ignoreCase, ignoreSpaces, and lives:

{
    "title": "Type 'hello' in either Italian, German, or French.",
    "type": "TextEntry",
    "answers": ["Ciao", "Hallo", "Bonjour"],
    "ignoreCase": true,
    "ignoreSpaces": true,
    "lives": 3
}

Add "Order it" questions

Properties

Property	Required	Type	Description	Default
`title`	✓	string	title of the question
`description`		string	description of the question
`type`	✓	string	set to `Order`
`items`	✓	string	an array of strings/items to order
`itemsShuffled`		boolean	If set to `true`, the order of the items/choices will be shuffled	false
`score`		integer	the score the user gets for answering this question correctly	1
`layoutType`		string	set to `Rows` or `Columns`	Rows
`rankFormat`		string	set to `Number`, `Letter`, or `NumberEnum`	Number
`showCorrectAnswerButton`		boolean	set to `true` to show the correct answer button	false
`guessesAreUnlimited`		boolean	set to `true` to allow unlimited guesses; if this is set to true none of the `guesses` properties below can be set.	false
`guesses`		integer	set to a number to give the user multiple attempts to answer the question	1
`guessesIcon`		string	set to `Heart`, `Numeric`, or `X`	Heart
`guessesDisplayLabel`		string	provide a string to display the # of remaining guesses
`upDownButtons`		boolean	If set to `true`, up and down buttons are shown to change the order of the items instead of drag and drop	true

Example objects

An example with only the required options:

{
    "title": "Order the following colors from lightest to darkest.",
    "type": "Order",
    "items": ["red", "blue", "green"]
}

An example with extensive configuration:

{
    "title": "Order the following colors from lightest to darkest.",
    "type": "Order",
    "items": ["red", "blue", "green"],
    "itemsShuffled": true,
    "score": 5,
    "layoutType": "Rows",
    "rankFormat": "Number",
    "showCorrectAnswerButton": true,
    "guesses": 3,
    "guessesIcon": "Heart",
    "guessesDisplayLabel": "Cat lives",
    "upDownButtons": false
}

Want to set the score per item? Learn more

Add flashcard questions

Properties

Property	Required	Type	Description
`title`	✓	string	title of the question
`description`		string	description of the question
`type`	✓	string	set to `Flashcard`
`hint`		string	hint for the question
`backside`	✓	object	object with `title` and optionally `description` + `media`; this is the content the user sees when flipping the flashcard

Example object

{
    "title": "Capital of germany",
    "description": "Germany is a country in Europe",
    "hint": "Starts with a 'B'",
    "type": "Flashcard",
    "backside": {
        "title": "Berlin",
        "description": "Berlin is the capital of Germany"
    }
}

Answer explanations

You can add an answer explanation to SingleChoice, MultipleChoice, and TextEntry questions.

To do this add an explanation object to the quiz question block configuration, consisting of:

Property	Required	Type	Description
`title`	✓	string	The title of the explanation
`description`		string	The description of the explanation
`media`		string	A media URL to an image to display as part of the explanation

If you wish to have an incorrect answer explanation, you can add the wrongExplanation with the same properties as explanation to the block. If only explanation is provided, it will be shown as an explanation for both correct and incorrect answers.

Example object

{
    "title": "Type 'hello' in either Italian, German, or French.",
    "type": "TextEntry",
    "answers": ["Ciao", "Hallo", "Bonjour"],
    "explanation": {
        "title": "My correct explanation",
        "description": "My correct explanation description",
        "media": "https://example.com/correct-image.jpg"
    },
    "wrongExplanation": {
        "title": "My wrong explanation",
        "description": "My wrong explanation description",
        "media": "https://example.com/wrong-image.jpg"
    }
}

Answer explanations & scores per item

Just as in the Riddle Creator, you can provide an explanation and score for each item/answer individually. This works for each Quiz block type with items, i.e. SingleChoice, MultipleChoice, Order. (In Order only the explanation can be set per answer)

Please note that you must either provide an explanation + a score for each answer, one for all, or none.

Example SingleChoice object:

{
    "title": "The best noodles?",
    "type": "SingleChoice",
    "items":  {
        "Spaghetti": {
            "isCorrect": true,
            "score": 2,
            "explanation": {
                "title": "Correct!",
                "description": "Spaghetti is the best noodle"
            }
        },
        "Fusilli": {
            "isCorrect": false,
            "score": 0,
            "explanation": {
                "title": "Incorrect!",
                "description": "Spaghetti is the best noodle"
            }
        }
    }
}

In the example above Spaghetti would be the correct choice and the user would get 2 points for selecting it. If they select Fusilli they would get 0 points and see the explanation "Spaghetti is the best noodle". This results in a maximum score of 2.

Example Order object:

{
    "title": "The best noodles?",
    "type": "Order",
    "items":  {
        "Spaghetti": {
            "score": 2
        },
        "Fusilli": {
            "score": 1
        }
    }
}

In the example above Spaghetti would be the correct choice and the user would get 2 points for putting it into the right order index. If they select Fusilli as second they would get 1 points and see the explanation "Spaghetti is the best noodle". This results in a maximum score of 3.

Result pages

In a quiz you can specify multiple result pages to segment users based on their scores. For example users who score between 0-50% will see one result, users who score between 51-100% will see another result. Each result has a title, description, minPercentage, and maxPercentage property.

As there can be multiple results, we store the results in an array in build.results:

[
    {
        "title": "My result 0-30%",
        "description": "Description 1",
        "minPercentage": 0,
        "maxPercentage": 50
    },
    {
        "title": "My result 31-100%",
        "description": "Description 2",
        "minPercentage": 51,
        "maxPercentage": 100
    }
]

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 blocks + options:

{
    "type": "Quiz",
    "build": {
        "title": "Quiz example (Builder API)",
        "blocks": [
            {
                "title": "What's the capital of Germany?",
                "type": "SingleChoice",
                "items": {
                    "Berlin": true,
                    "Lissabon": false,
                    "Leipzig": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Berlin is the capital of Germany"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Berlin is the capital of Germany"
                }
            },
            {
                "title": "What are valid colors in German?",
                "type": "MultipleChoice",
                "items": {
                    "rot": true,
                    "schwarz": true,
                    "nero": false
                },
                "explanation": {
                    "title": "Correct!",
                    "description": "Berlin is the capital of Germany"
                }
            },
            {
                "title": "Type 'hello' in either Italian, German, or French.",
                "type": "TextEntry",
                "answers": [
                    "Ciao",
                    "Hallo",
                    "Bonjour"
                ],
                "explanation": {
                    "title": "Correct!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "wrongExplanation": {
                    "title": "Incorrect!",
                    "description": "Ciao, Hallo, and Bonjour all mean 'hello'"
                },
                "ignoreCase": true,
                "ignoreSpaces": true,
                "lives": 3
            },
            {
                "title": "Order the following colors from lightest to darkest.",
                "type": "Order",
                "items": [
                    "red",
                    "blue",
                    "green"
                ],
                "itemsShuffled": true,
                "guesses": 3
            },
            {
                "title": "Capital of Germany",
                "description": "Germany is a country in Europe",
                "hint": "Starts with a 'B'",
                "type": "Flashcard",
                "backside": {
                    "title": "Berlin",
                    "description": "Berlin is the capital of Germany"
                }
            }
        ],
        "results": [
            {
                "title": "Not so good...",
                "description": "There's room for improvement",
                "minPercentage": 0,
                "maxPercentage": 50
            },
            {
                "title": "Well done!",
                "description": "You're a winner",
                "minPercentage": 51,
                "maxPercentage": 100
            }
        ]
    }
}

Build RiddlesCreate Poll - Build Riddles

Build RiddlesCreate a Personality Test - Build Riddles