Skip to main content

​
Method Signature

constructorio.quizzes.getQuizNextQuestion(quizId, parameters, networkParameters)
Retrieves the next question from a quiz. On the first call, returns the initial question. On subsequent calls with answers provided, returns the next appropriate question based on the quiz logic.

​
Parameters

​
quizId
string
required
The unique identifier of the quiz.
​
parameters
object
Additional parameters to refine the request.
​
networkParameters
object
Parameters relevant to the network request.

​
Returns

Returns a Promise that resolves to a NextQuestionResponse object.
​
next_question
Question
required
The next question object. The structure varies based on question type.
​
quiz_version_id
string
Version identifier for the quiz. Must be included in all subsequent requests.
​
quiz_id
string
The identifier of the quiz.
​
quiz_session_id
string
Session identifier for the quiz. Must be included in all subsequent requests.
​
total_questions
number
The total number of questions in the quiz.

​
Examples

​
Get First Question

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

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

const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz');

console.log(response.next_question.title);
// "What are you shopping for?"

// Store these for subsequent requests
const quizVersionId = response.quiz_version_id;
const quizSessionId = response.quiz_session_id;
const totalQuestions = response.total_questions;

​
Get Next Question with Answers

// User answered the first question by selecting options 1 and 2
const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz', {
  answers: [[1, 2]],
  quizVersionId: 'abc123',
  quizSessionId: 'session456',
});

console.log(response.next_question.title);
// Next question based on previous answers

​
Multiple Questions with Different Answer Types

// After multiple questions answered
const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz', {
  answers: [
    [1, 2],      // Multiple choice - selected options 1 and 2
    [3],         // Single choice - selected option 3
    ["true"],    // Boolean - answered true
    ["seen"],    // Cover question - acknowledged
  ],
  quizVersionId: 'abc123',
  quizSessionId: 'session456',
});

​
Skip Tracking for Preload

// Preload the first question without tracking
const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz', {
  skipTracking: true,
});

// Display the question to the user
// When they actually interact with it, make another call without skipTracking

​
With Section Filter

const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz', {
  section: 'Men',
  answers: [[1]],
  quizVersionId: 'abc123',
  quizSessionId: 'session456',
});

​
With Network Timeout

try {
  const response = await constructorio.quizzes.getQuizNextQuestion(
    'product-finder-quiz',
    {
      answers: [[1, 2]],
      quizVersionId: 'abc123',
      quizSessionId: 'session456',
    },
    {
      timeout: 5000, // 5 seconds
    }
  );
} catch (error) {
  console.error('Request timed out or failed:', error);
}

​
Handling Different Question Types

const response = await constructorio.quizzes.getQuizNextQuestion('product-finder-quiz');

const question = response.next_question;

switch (question.type) {
  case 'single':
    // Render radio buttons
    console.log('Select one:', question.options);
    break;
  
  case 'multiple':
    // Render checkboxes
    console.log('Select all that apply:', question.options);
    break;
  
  case 'open':
    // Render text input
    console.log('Enter your answer:', question.input_placeholder);
    break;
  
  case 'cover':
    // Render informational screen
    console.log(question.title, question.description);
    break;
  
  case 'single_filter_value':
  case 'multiple_filter_values':
    // Render options that map to product filters
    console.log(`Filter: ${question.filter_name}`);
    console.log('Options:', question.options);
    break;
}

​
Error Handling

try {
  const response = await constructorio.quizzes.getQuizNextQuestion('quiz-id', {
    answers: [[1, 2]],
    quizVersionId: 'abc123',
    quizSessionId: 'session456',
  });
} catch (error) {
  if (error.message === 'quizId is a required parameter of type string') {
    console.error('Quiz ID is required');
  } else if (error.message === 'getQuizNextQuestion response data is malformed') {
    console.error('Invalid response from server');
  } else {
    console.error('Request failed:', error);
  }
}

​
Notes

  • Always store quiz_version_id and quiz_session_id from the first response and include them in all subsequent requests
  • The answers array should contain one entry per question answered, in order
  • Use skipTracking: true when preloading questions to avoid inflating analytics
  • The response will throw an error if quiz_version_id is not present, indicating a malformed response
  • Question types determine which fields are available in the next_question object

​
API Reference

Build docs developers (and LLMs) love

Get started for freeTalk to us