Multiple Choice

Multiple choice questions are fundamental survey questions that provide respondents with multiple answer options. Primarily, multiple-choice questions can have single-select or multiple-select answer options. These are the most fundamental questions of a survey or questionnaire where the respondents are expected to select one or more than one option from the multiple answer options.

Whenever we think of conducting surveys, we think of two things: the kind of questions to ask and data collected from the answers to those questions. Essentially, the most important aspect of surveys is to formulate relevant questions that will help us extract clean data.

Managing Multiple Choice

The Multiple Choice API enables you to form the basis of any survey or questionnaire by providing a set of answer options that users can select. These are the perfect way to understand people's preferences and collect valuable results. This type of question not only brings balance to the survey, but also makes it easier, more enjoyable and faster to answer.

This API is used for creating, playing, and obtaining questions, answers and player's scores.

Developers can integrate this API to launch their projects faster and will appreciate the seamless integration of trivia or multiple-choice question APIs into their websites and applications. Even they can save time in building question-and-answer functionality into their webs

The steps to create and play multiple-choice questions are the following:

Creating Multiple Choice

Multiple-choice questions consist of two essential parts: the Question and the Answer Options.

Multiple choice questions can be used in any setting when there is more than one possible answer.

The first step is to create and configure the multiple choice before defining the questions which the user will play.

At this point, you need to define the number of questions that a round has, for example, the cycles are 10 questions, so if the user answers 8 questions correctly, he will win a prize depending on the interactive campaign you want to include in your project, for example, a Trivia game. You also need to define the expiration time for each question, configure a final message once the user finishes his round of questions and establish an order according to each question created (setup cycle). The Question List currently supports two types of ordering:

  • Random : Each question will be randomly displayed once the user has started the game.

  • Order : Each question will be displayed according to the order in which they were created.

📘

NOTE

In Multiple Choice there are no right or wrong answers, but each answer will have a certain effect.

When you create a Multiple Choice, the request body contains the following data:

HTTP Request : POST /v1/mchoice

{
  "name": "Game A",
  "cycleSetup": "random",
  "cycleRound": 4,
  "resetQuestions": true,
  "expirationTime": 10000,
  "endMChoiceRoundMessage": "thank you for playing"
}

The parameters presented in the request body example when creating the multiple choice are the following:

Parameter Required Description
name Yes

Name of the game

cycleSetup Yes

There are two cycle setups :

  • "random": the questions will be random.
  • "order": the questions will be ordered.

cycleRound Yes

The total number of questions a round has.

resetQuestions Yes

  • "true": reset question history when there are no more questions to play.
  • "false": does not reset question history when there are no more questions to play.

expirationTime Yes

Question expiration time (milliseconds).

endMChoiceRoundMessage Yes

Final round message (optional).

When you have created the multiple choice, the response body contains the following data :

{
  "meta": {
    "timestamp": 1620696712042,
    "transactionId": "14dcb92b-be1a-4e99-b6ab-e342feb0537f"
  },
  "data": {
    "id": 234,
    "name": "Game A",
    "owner": "[email protected]",
    "operator": null,
    "cycleSetup": "random",
    "cycleRound": 4,
    "maxRounds": null,
    "resetQuestions": true,
    "expirationTime": 10000,
    "endMChoiceRoundMessage": "thank you for playing"
  }
}

We only describe the additional parameters that are generated when making the request.

To consult each description parameter (not additional parameters) displayed in the response body example, go to the parameters presented in the request body example when creating the multiple choice.

The additional parameters presented in the response body example when creating the multiple choice are the following:

Parameter Description
data Data contained in the multiple choice information.
data.
id
Unique identifier of the multiple choice.
data.
owner
Owner or creator of the multiple choice.

Getting Multiple Choice

When the Multiple Choice is previously created, you proceed to get the specific data from a single multiple choice.

HTTP Request : GET /v1/mchoice/{id}

To get a multiple choice, you must provide the unique identifier of the multiple choice for which you want to retrieve the information.

Required ParameterDescription
idUnique identifier of the multiple choice.

Creating Questions

Create multiple choice questions in JSON format.

The primary bifurcation of these questions is based on the number of answer options the respondents can select while responding to the survey. So, single choice questions and multiple choice (multiple answer) questions are the two available main question types:

  • Single Select Multiple Choice Question : single select questions are the questions where a respondent is asked to pick only one correct answer, from a predetermined set of responses of at least two or more options.



  • Multi select Multiple Choice Questions : multi select multiple choice questions are similar to Multiple Choice questions. There is a slight difference in this question type, that these types of questions can have more than one correct answer. You can create as many choices as necessary.


    Questions might be added one by one or in bulk by sending their basic information (Question / answers).

Creating single questions

You have the option to create one by one question and define the score for each correct question. That is, if the user gets a question right, increase their score by the point value of the question. Even this API allows you to differentiate the (textual) options that the user can play. For example, I set the number 1(keyword value) in the most viable option for the user to answer.

HTTP Request : POST /v1/mchoice/{mchoiceid}/question

Before creating a single question, you must provide the unique identifier of the multiple choice.

Required ParameterDescription
mchoiceidUnique identifier of the multiple choice.

When you create a single question, the request body contains the following data:

{
  "text": "What are the programming languages created in the 80s?",
  "answers": [
    {
      "text": "Python",
      "keywords": [
        "1"
      ],
      "action": "NEXT"
    },
    {
      "text": "C++",
      "keywords": [
        "2"
      ],
      "action": "NEXT",
      "actionParams": {
        "correct": true,
        "reward": 20
      }
    },
    {
      "text": "Java",
      "keywords": [
        "3"
      ],
      "action": "NEXT"
    },
    {
      "text": "Perl",
      "keywords": [
        "4"
      ],
      "action": "NEXT",
      "actionParams": {
        "correct": true,
        "reward": 20
      }
    }
  ]
}

Creating multiple questions

There are two options to create multiple questions:

  • Create bulk questions by JSON

  • Create bulk questions by CSV

When you create multiple subscribers and define the score for each correct question or differentiate the (textual) options that the user can play, you have the option to overwrite (query parameter) the questions. That is, questions that were created earlier will be inactive (they won't repeat and disable all previous stored questions), except for the question that is about to be played. Once the user answers the question, it will remain inactive and each new question created in bulk will be displayed.

HTTP Request : POST /v1/mchoice/{mchoiceid}/question/batch

📘

NOTE

The points (score) that the user accumulated will not be lost if the questions are overwritten.

❗️

WARNING

There is a query parameter called “Purge” to purge the questions. We recommend using this parameter in case the trivia or multiple choice has not started yet because the questions and the user's score will be erased.

Before creating bulk questions, you must provide the unique identifier of the multiple-choice question.

Required ParameterDescription
mchoiceidUnique identifier of the multiple choice.

When you create bulk questions at once by JSON, the request body contains the following data:

{
  "questions": [
    {
      "text": "What are the programming languages created in the 80s?",
      "answers": [
        {
          "text": "Python",
          "keywords": [
            "1"
          ],
          "action": "NEXT"
        },
        {
          "text": "C++",
          "keywords": [
            "2"
          ],
          "action": "NEXT",
          "actionParams": {
            "correct": true,
            "reward": 20
          }
        },
        {
          "text": "Java",
          "keywords": [
            "3"
          ],
          "action": "NEXT"
        },
        {
          "text": "Perl",
          "keywords": [
            "4"
          ],
          "action": "NEXT",
          "actionParams": {
            "correct": true,
            "reward": 20
          }
        }
      ]
    },
    {
      "text": "What is the capital of Japan?",
      "answers": [
        {
          "text": "Tokushima",
          "keywords": [
            "1"
          ],
          "action": "NEXT"
        },
        {
          "text": "Toyama",
          "keywords": [
            "2"
          ],
          "action": "NEXT"
        },
        {
          "text": "Tokyo",
          "keywords": [
            "3"
          ],
          "action": "NEXT",
          "actionParams": {
            "correct": true,
            "reward": 20
          }
        },
        {
          "text": "Tottori",
          "keywords": [
            "4"
          ],
          "action": "NEXT"
        }
      ]
    }
  ]
}

The parameters presented in the request body example when creating single or multiple questions are the following:

Parameter Required Description
questions Yes

Array of multiple choice question objects. Each object in this array defines an individual question and its associated answers.

questions.
text
Yes

Represents the actual question text that will be displayed to the respondent.

questions.
answers
Yes

An array of answer objects corresponding to the question.

questions.
answers.
text
Yes

Defines the answer option displayed to the user.

questions.
answers.
keywords
Yes

Identifiers associated with the answer. That is, differentiate each option to answer the question. (Value option)

questions.
answers.
action
Yes

Specifies the action to be triggered when the answer is selected.

When answering the question, continue with the next question.

questions.
answers.
actionParams
Yes

Optional object that contains metadata related to the selected answer. This is used when the answer has additional logic, such as being marked as correct or carrying a reward.

  • "BLACK"
questions.
answers.
actionParams.
correct
Yes

  • "true": Indicates the selected answer is correct.
  • "false": Indicates the selected answer is incorrect.

questions.
answers.
actionParams.
reward
Yes

Specifies the number of points to assign for selecting a correct answer.

When you create a single question, the response body contains the following data:

{
  "meta": {
    "timestamp": 1620697375502,
    "transactionId": "616689ee-00c2-4416-a878-c71fd4cbfd66"
  },
  "data": {
    "id": 1236,
    "text": "What are the programming languages created in the 80s",
    "mChoice": 234,
    "answers": [
      {
        "text": "Python",
        "keywords": [
          "1"
        ],
        "question": null,
        "action": "NEXT",
        "actionParams": null
      },
      {
        "text": "C++",
        "keywords": [
          "2"
        ],
        "question": null,
        "action": "NEXT",
        "actionParams": {
          "correct": "true",
          "reward": "20"
        }
      },
      {
        "text": "Java",
        "keywords": [
          "3"
        ],
        "question": null,
        "action": "NEXT",
        "actionParams": null
      },
      {
        "text": "Perl",
        "keywords": [
          "4"
        ],
        "question": null,
        "action": "NEXT",
        "actionParams": {
          "correct": "true",
          "reward": "20"
        }
      }
    ]
  }
}

We only describe the additional parameters that are generated when making the request.

To consult each description parameter (not additional parameters) displayed in the response body example, go to the parameters presented in the request body example when creating the questions.

The additional parameters presented in the response body example when creating a single question are the following:

Parameter Description
data Data contained in the questions information.
data.
id
Unique identifier of the question.
data.
mChoice
Unique identifier of the multiple choice.

When you created bulk questions by JSON, the response body contains the following data:

{
  "meta": {
    "timestamp": 1620702217872,
    "transactionId": "fbfde39b-d60a-4b8f-b476-54e70817a735"
  },
  "data": {
    "count": 2
  }
}

In case you created bulk questions by JSON or CSV, the response body contains the following data:

Parameter Description
data Data contained in the questions information.
data.
count
Total number of questions created.

To verify and get the questions for a Multiple Choice you have created, go to

Play Multiple Choice

Play Multiple Choice is a form of quiz game in which you can attempt to answer the quiz questions correctly. It is a quiz game to test the user knowledge about certain subjects and win points.

Before the user plays, you need to provide the unique identifier of the user who will play the multiple choice in the request body.

Once the game is started, the input parameter allows the player to answer the question by entering the option (answer) that he considers correct for each question.

HTTP Request : POST /v1/play/{mchoiceid}

{
  "playerId": "elizabeth78",
  "input": "1"
}

To play the multiple choice, you need to provide the unique identifier of the multiple choice.

Required ParameterDescription
mchoiceidUnique identifier of the multiple choice.

When the user has started the game, the statistics of each round played by the user will be displayed in the response body :

  • The round number the player is currently in.

  • The player is going to answer a new question.

  • The total number of questions that the round has.

  • Total number of correct questions the player has responded to.

For example, in the following response body, the player is currently in round 1. Each round has 4 questions. The player has answered the 1 question correctly, and the unique identifier of the question to answer is 656. The question ID helps you to check the question number the player is currently on.

{
  "meta": {
    "timestamp": 1619913703733,
    "transactionId": "ab875d88-041d-4480-9147-5bb9f6650b04"
  },
  "data": {
    "params": {
      "reward": 20,
      "input": true,
      "correct": true
    },
    "playerId": "elizabeth78",
    "text": "What is the capital of Japan?",
    "choices": [
      {
        "text": "Tokushima",
        "keywords": [
          "1"
        ]
      },
      {
        "text": "Toyama",
        "keywords": [
          "2"
        ]
      },
      {
        "text": "Tokyo",
        "keywords": [
          "3"
        ]
      },
      {
        "text": "Tottori",
        "keywords": [
          "4"
        ]
      }
    ],
    "stats": {
      "1": {
        "total": 4,
        "correct": 1,
        "questionSet": [
          659,
          654,
          656
        ]
      }
    },
    "currentRound": 1
  }
}

The parameters presented in the response body example when the player has started to play the multiple choice are the following:

Parameter Description
data Data contained in the game information.
data.
params
Holds metadata about the response submitted by the user.
data.
params.
reward
Points earned by the player for a correct answer.
data.
params.
input

Indicates whether an answer was submitted:

  • "true": input was provided.
  • "false": no input received.
data.
params.
correct
Shows if the submitted answer was correct (true) or incorrect (false).
data.
playerId
Unique identifier of the player.
data.
text
The actual question being asked in the current round.
data.
choices
List of answer options presented for the current question.
data.
choices.
text
Text displayed for each answer option.
data.
choices.
keywords
A unique identifier for each choice that helps distinguish between answer options
data.
stats
Contains performance metrics for the player's current session, organized per round.
data.
stats.
total
Total number of questions in the round.
data.
stats.
correct
Number of questions answered correctly by the player.
data.
stats.
questionSet
Collection of questions with their respective Id.
data.
currentRound
The current round the player is in.

Player Record

You can get the record of points made by the player.

HTTP Request : GET /v1/play/{mchoiceid}/score/{playerId}

To get the player's score, you need to provide the unique identifier of the multiple choice and the player Id. If you want to get the player's score for a specific round, provide the round number.

Required ParameterDescription
mchoiceidUnique identifier of the multiple choice.
playerIdUnique identifier of the player.
roundRound number