Multiple Choice

Multiple choice questions are fundamental survey questions which provide respondents with multiple answer options. Primarily, multiple choice questions can have single select or multi 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 Choices

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 a multiple choice questions are the following:

  • Create Multiple Choice

  • Create Questions

  • Play Multiple Choice

Creating Multiple Choice

Multiple-choice questions consist of two essential parts: the question and the answer options.

561

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:

ParameterDescription
nameGame Name
cycleSetupThere are currently two cycle setups :

- random : the questions will be random.

- order : the questions will be ordered.
cycleRoundTotal number of questions a round has.
resetQuestiontrue : 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.
expirationTimeQuestion expiration time (milliseconds).
endMChoiceRoundMessageFinal 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": "root",
    "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:

ParameterDescription
dataData contains the multiple choice information.
idMultiple Choice Id
ownerMultiple choice owner

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 need to provide the unique identifier of the multiple choice you want to retrieve the information.

Required ParameterDescription
idMultiple Choice Id

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.
381
  • 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.
381

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

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
      }
    }
  ]
}

To create a single question, you need to provide the unique identifier of the multiple choice.

Required ParameterDescription
mchoiceidMultiple Choice ID

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.

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"
        }
      ]
    }
  ]
}

To create bulk questions, you need to provide the unique identifier of the multiple choice.

Required ParameterDescription
mchoiceidMultiple Choice Id

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

ParameterDescription
questionsCollection of questions.
textInterrogative expression used to test knowledge (Question).
answersCollection of answers.
answers.textResponse (option) to a specific question.
keywordsDifferentiate each option to answer the question. (Value option)
actionWhen answering the question, continue with the next question.
actionParamsAction parameters.
correcttrue : correct answer.

false : wrong answer.
rewardResponse score (points).

When you created 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:

ParameterDescription
dataData contains the questions information
idQuestion Id
mChoiceMultiple Choice Id

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 the following data:

ParameterDescription
dataData contains the questions information.
countTotal 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"
}

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

  • Round number the player is currently in.

  • New question the player is going to answer.

  • Total number of questions which the round has.

  • Total number of correct questions the player has answered.

For example, in the following response body, the player is currently in round 1. Each round has 4 questions. The player has answered 1 question correctly and the unique identifier of the question to answer 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 sted to play the multiple choice are the following:

ParameterDescription
dataData contains the Game information.
paramsParameters
rewardAdd up the points (score) obtained for each question answered correctly.
inputtrue : response value (option) was entered.

null : response value (option) was not entered.
correcttrue : correct answer

false : wrong answer
playerIdUnique identifier of the player.
textInterrogative expression used to test knowledge (Question).
choicesSet of options available to answer the question.
choices.textResponse (option) to a specific question.
keywordsDifferentiate each option to answer the question. (Value option)
statsContains information for each round played.
totalTotal number of questions a round has.
stats.correctTotal number of questions that have been answered correctly.
questionSetCollection of questions with their respective Id.
currentRoundThe current round the player is in.

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

Required ParameterDescription
mchoiceidMultiple Choice Id

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
mchoiceidMultiple Choice Id
playerIdPlayer Id
roundRound number