Create Predictor

When building a predictor you can add:

Predictor questions: GuessTheScore and PickTheWinner
Form fields: FormBuilder, standalone FormField blocks, or an embedded FormSelect
General blocks: Content, Quote, and Ad
One result page
The scoring rules of the predictor, via build.scoring

A predictor has no custom logic tree - build.logic is not available for this Riddle type. What a prediction is worth is configured through build.scoring instead (see below).

GuessTheScore / PickTheWinner

Both types describe the same thing - two parties and a prediction about them - but they are not configured identically: PickTheWinner (pick which of the two wins) supports a description and a draw option, GuessTheScore (guess the exact result) does not.

Properties

Property	Required	Type	Description	Default
`type`	✓	string	Set to `GuessTheScore` or `PickTheWinner`
`title`	✓	string	The question title
`items`	✓	object	Exactly 2 predictor items; see below - see item formats
`description`		string	`PickTheWinner` only: a description below the title
`isDrawEnabled`		boolean	`PickTheWinner` only: whether a tie between the two items is a pickable outcome	true
`correctResult`		integer	Edit only (see below): the real-world outcome, as the two scores in the order of `items`

Note: items must contain exactly 2 items - no more, no less - for both GuessTheScore and PickTheWinner. A predictor item carries the name of its party in title and takes no description or media - its visuals are the properties below (see item formats).

Predictor questions have no general media - the visuals live on the two items (backgroundImage, logo).

Example:

{
    "title": "Who will win?",
    "type": "PickTheWinner",
    "items": [
        {
            "title": "Team A"
        },
        {
            "title": "Team B"
        }
    ]
}

The example above is very basic - if you want to go beyond that, each item in items supports:

Property	Required	Type	Description	Default
`title`	✓	string	The name of this party, e.g. the team name
`backgroundImage`		string\|object	Media shown as the background of the item; e.g. a stadium photo. See Use media
`logo`		string\|object	Media shown as the item's logo; e.g. the logo of a sports team
`backgroundColor`		string	Hex color of the item background	#1D2025
`textColor`		string	Hex color of the item text	#fff

Example with all optional properties set:

{
    "title": "Who will win?",
    "type": "PickTheWinner",
    "items": [
        {
            "title": "Team A",
            "backgroundImage": "https://httpbin.io/image/jpeg",
            "logo": "https://httpbin.io/image/png",
            "backgroundColor": "#FF0000",
            "textColor": "#FFFFFF"
        },
        {
            "title": "Team B",
            "backgroundImage": "https://httpbin.io/image/jpeg",
            "logo": "https://httpbin.io/image/png",
            "backgroundColor": "#0000FF",
            "textColor": "#FFFFFF"
        }
    ]
}

Note: backgroundImage and backgroundColor may be set together - they are layers, not alternatives: the backgroundColor renders as a semi-transparent tint over a grayscaled backgroundImage. Set only backgroundColor for a flat colored item, or set both to tint a photo in your team's color.

Note: Do not supply an id property for predictor items - IDs are automatically assigned as 0 and 1. An id that already matches the item's position (0 for the first, 1 for the second) is accepted, so a build config you read back via the API stays re-buildable; any other value is rejected.

The real result (`correctResult`)

correctResult is what turns collected predictions into scores: the outcome that actually happened. It is the counterpart of the "Correct results" step you see in the Creator when you publish a predictor, and it takes the two scores as a list, in the order of the block's items:

GuessTheScore: the actual scores, as whole numbers of 0 or more - [3, 1] means the first item scored 3 and the second 1.
PickTheWinner: which side won, not a score - [1, 0] (the first item won), [0, 1] (the second won), or [1, 1] for a draw. A value above 1 is rejected here.
[0, 0] means "no outcome yet" for both types, and is how you clear a result you set earlier.

correctResult can only be set when editing a Riddle that already exists - i.e. through the edit endpoint, never while creating the Riddle or while adding the block with a $create marker. A real-world outcome only exists once the match has been played, which is always after the predictor was built; sending it on a create is rejected with an error telling you to set it in a follow-up edit.

Example (editing an existing predictor, 2 being the ID of the predictor block):

{
    "blocks": [
        {
            "id": 2,
            "correctResult": [3, 1]
        }
    ]
}

Scoring

build.scoring defines how many points a prediction earns. All four values are optional and must be integers of 0 or more:

Property	Type	Description	Default
`correct`	integer	Points for an exactly correct prediction (the winner, or both scores, match)	30
`tendency`	integer	Points for calling only the winning side/tendency correctly	10
`difference`	integer	`GuessTheScore`: points when the guessed score margin matches, even if the exact scores do not	20
`wrong`	integer	Points for a prediction that is wrong outright	0

Example:

{
    "type": "Predictor",
    "build": {
        "title": "Predictor with custom scoring",
        "scoring": {
            "correct": 50,
            "tendency": 20,
            "difference": 30,
            "wrong": 0
        },
        "blocks": [
            {
                "title": "Who will win?",
                "type": "PickTheWinner",
                "items": [
                    { "title": "Team A" },
                    { "title": "Team B" }
                ]
            }
        ]
    }
}

Result page

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

Example:

{
    "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 both question types + options, a general block and a form:

{
    "type": "Predictor",
    "build": {
        "title": "Predictor example (Builder API)",
        "scoring": {
            "correct": 30,
            "tendency": 10,
            "difference": 20,
            "wrong": 0
        },
        "blocks": [
            {
                "type": "Content",
                "title": "Predict this weekend's matches",
                "description": "The most accurate prediction wins."
            },
            {
                "title": "Who will win?",
                "type": "PickTheWinner",
                "description": "Pick the team you think takes the trophy.",
                "isDrawEnabled": false,
                "items": [
                    {
                        "title": "Team A",
                        "backgroundImage": "https://httpbin.io/image/jpeg",
                        "logo": "https://httpbin.io/image/png",
                        "backgroundColor": "#FF0000",
                        "textColor": "#FFFFFF"
                    },
                    {
                        "title": "Team B",
                        "backgroundImage": "https://httpbin.io/image/jpeg",
                        "logo": "https://httpbin.io/image/webp",
                        "backgroundColor": "#0000FF",
                        "textColor": "#FFFFFF"
                    }
                ]
            },
            {
                "title": "What will be the score?",
                "type": "GuessTheScore",
                "items": [
                    {
                        "title": "Team A"
                    },
                    {
                        "title": "Team B"
                    }
                ]
            },
            {
                "title": "Where should we send your winnings?",
                "type": "FormBuilder",
                "fields": [
                    { "title": "Your name", "type": "Name" },
                    {
                        "title": "Your email",
                        "type": "Email",
                        "isRequired": true,
                        "requiredMessage": "We need your email to notify you."
                    }
                ]
            }
        ],
        "result": {
            "title": "Thank you!",
            "description": "We are happy to have you here"
        }
    }
}

Note: A predictor also accepts standalone FormField blocks, a FormSelect, and the Quote/Ad general blocks. build.logic is the one thing it does not support.

Next steps

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

Riddle Types And Other BlocksCreate a Personality Test - Build Riddles

Riddle Types And Other BlocksCreate and connect to Leaderboard - Build Riddles