Skip to main content
The Quizzes module provides methods to create interactive quiz experiences that guide users to personalized product recommendations.

​
Key Concepts

​
Quiz Flow

A typical quiz implementation follows this flow:
  1. Get Next Question - Fetch the first question or subsequent questions based on previous answers
  2. Collect Answers - Present questions to users and collect their responses
  3. Get Results - Retrieve personalized product recommendations based on all answers

​
Session Management

Quizzes use two key identifiers to maintain state:
  • Quiz Version ID - Returned with the first request and must be passed with all subsequent requests
  • Quiz Session ID - Returned with the first request and must be passed with all subsequent requests
These identifiers ensure consistency throughout the quiz experience. Learn more in the Configuration Guide.

​
Answer Format

Answers are provided as a nested array where each inner array represents responses to a single question: 
[
  [1, 2],      // Multiple choice question - selected options 1 and 2
  [1],         // Single choice question - selected option 1
  ["true"],    // Boolean question - answered true
  ["seen"],    // Acknowledged/seen a cover question
  [""]         // Skipped question
]
Based on the question type, answers can be:
  • Integer - For single/multiple choice questions (option IDs)
  • “true”/“false” - For boolean questions
  • “seen” - For cover/acknowledgment questions
  • Empty string "" - For skipped questions
  • Text - For open-ended questions

​
Available Methods

Get Next Question

Retrieve the next question in a quiz based on previous answers

Get Results

Get personalized product recommendations based on quiz answers

​
Basic Example

const ConstructorIO = require('@constructor-io/constructorio-client-javascript');

const constructorio = new ConstructorIO({
  apiKey: 'YOUR_API_KEY',
});

// Step 1: Get the first question
const firstQuestion = await constructorio.quizzes.getQuizNextQuestion('quiz-id');

console.log(firstQuestion.next_question);
// Store these for subsequent requests
const quizVersionId = firstQuestion.quiz_version_id;
const quizSessionId = firstQuestion.quiz_session_id;

// Step 2: Get the next question with answers
const secondQuestion = await constructorio.quizzes.getQuizNextQuestion('quiz-id', {
  answers: [[1, 2]], // User selected options 1 and 2
  quizVersionId,
  quizSessionId,
});

// Step 3: Get results after all questions are answered
const results = await constructorio.quizzes.getQuizResults('quiz-id', {
  answers: [
    [1, 2],      // First question answers
    [3],         // Second question answer
    ["true"],    // Third question answer
  ],
  quizVersionId,
  quizSessionId,
});

console.log(results.response.results); // Product recommendations

​
Question Types

The API supports various question types:

​
Single Choice

Users select one option from a list. 
type: 'single'
options: QuestionOption[]

​
Multiple Choice

Users can select multiple options from a list. 
type: 'multiple'
options: QuestionOption[]

​
Single Filter Value

Users select one value that maps to a product filter. 
type: 'single_filter_value'
filter_name: string
options: FilterQuestionOption[]

​
Multiple Filter Values

Users can select multiple values that map to product filters. 
type: 'multiple_filter_values'
filter_name: string
options: FilterQuestionOption[]

​
Open-Ended

Users provide free-form text input. 
type: 'open'
input_placeholder?: string

​
Cover

Introductory or informational screen with no input required. 
type: 'cover'

​
Error Handling

try {
  const question = await constructorio.quizzes.getQuizNextQuestion('quiz-id');
} catch (error) {
  if (error.message.includes('quizId is a required parameter')) {
    // Handle missing quiz ID
  }
  console.error('Quiz error:', error);
}

Build docs developers (and LLMs) love

Get started for freeTalk to us