​
Overview

The multiplayer quiz flow in IntelliQ involves several API endpoints that handle quiz generation, submission, and leaderboard functionality. This guide explains the complete flow from quiz creation to viewing results.

​
Flow Diagram

  1. Generate Quiz (Admin Only) 
    GET /api/v1/quizzes/generate
    Generate a new quiz with specified parameters: 
    ?quizTopic=formula%20one&numberOfQuestions=2&language=en&quizType=multiplayer
    The response includes the quiz structure with questions and answers.
  2. Create Quiz Room (Admin Only) 
    POST /api/v1/quiz-submissions/{roomId}/quiz
    Create a new quiz room with the generated quiz content. The roomId is a unique identifier for the multiplayer session. The response includes:
    • quizId: Unique identifier for the quiz
    • questions: Array of questions with their IDs
  3. Get Quiz Questions (Players) 
    GET /api/v1/quiz-submissions/{roomId}/questions
    Players retrieve quiz questions without correct answers. Response includes:
    • Quiz title and ID
    • Questions with options (no correct answers)
    • Question IDs for submission
  4. Submit Answers (One at a time) 
    POST /api/v1/quiz-submissions/{roomId}/submissions
    Players submit answers one at a time, with the time taken to answer: 
    {
  "questionId": "question-uuid",
  "userAnswer": "selected answer",
  "timeTaken": 3500
}
    The server:
    • Validates if the answer is correct
    • Calculates points based on time taken using the formula: points = Math.round((1 - (timeTaken / timeLimit) / 2.2) * 1000)
    • Adds bonus points for fast answers (under 10% of time limit)
    • Updates the user’s total score
    • Returns the calculated score and submission details
  5. View Leaderboard 
    GET /api/v1/quiz-submissions/{roomId}/leaderboard
    Retrieve the current leaderboard for the quiz room, showing all players’ scores and correct answers.

​
Response Examples

{
  "quiz": {
    "quizTitle": "Formula One Trivia Challenge",
    "questions": [
      {
        "questionTitle": "The Fastest Lap Record",
        "text": "Which driver holds the record for the fastest lap in Formula One history?",
        "options": ["a) Lewis Hamilton", "b) Michael Schumacher", "c) Max Verstappen", "d) Sebastian Vettel"],
        "correctAnswer": "c) Max Verstappen"
      }
    ]
  }
}

​
Scoring Mechanics

The time-based scoring system rewards both accuracy and speed:
  1. Base Formula: points = Math.round((1 - (timeTaken / timeLimit) / 2.2) * 1000)
  2. Fast Answer Bonus: +50 points for answers under 10% of the time limit
  3. Minimum Points: All correct answers earn at least 100 points
  4. Incorrect Answers: 0 points
Each user’s total score accumulates as they answer questions, and their submission record is updated rather than creating multiple records.

​
Error Handling

The API will return appropriate error codes and messages if:
  • The quiz generation parameters are invalid
  • The room ID doesn’t exist
  • The question ID is invalid or doesn’t belong to the quiz
  • The user is not authorized to access the room
Written by Ricky Raveanu