Create a Quiz

Create a new quiz within a namespace.

---

Overview

This endpoint allows you to create a new quiz with customizable appearance, behavior, and scheduling options.

Method: POST
Endpoint:
/api/v1/namespaces/:namespaceId/quizzes

Requires administrative authentication.

---

Request

Headers

x-api-key: {your_api_key}  # Required
Content-Type: application/json

Path Parameters

Parameter	Type	Required	Description
namespaceId	string	✅	Namespace unique ID

Body Parameters

Parameter	Type	Required	Description
name	string	✅	Name of the quiz
start	date	✅	JavaScript timestamp when the quiz becomes active, must be in the future
end	date	✅	JavaScript timestamp when the quiz closes, must be in the future
questions	array	❌	Array of question objects, each containing an id from predefined question types and optional required boolean
primaryColor	string	❌	Hex color code for the quiz theme (#RRGGBB or #RGB format)
retryAfterDays	integer	❌	Number of days to wait before retry, must be 0 (for no retry) or greater
anonymous	boolean	❌	Indicates if the quiz allows anonymous responses (defaults to true)
inapp	boolean	❌	Indicates if the quiz is of the "InApp" type (defaults to false)
disableEmailing	boolean	❌	Prevents the quiz from sending emails (defaults to true)
customIntroScreen	object	❌	Custom introduction screen configuration
customOutroScreen	object	❌	Custom conclusion screen configuration
customLogo	string/object	❌	Custom logo URL or object
demographicMessage	string	❌	Custom message for demographic section
hasCustomIntro	boolean	❌	Indicates if quiz uses custom intro screen
hasCustomOutro	boolean	❌	Indicates if quiz uses custom outro screen
customCTA	object	❌	Custom call-to-action configuration
fhscore	boolean	❌	Enable financial health scoring for user results page (defaults to false)
customRecommendationCard	object	❌	Custom recommendation card configuration

customIntroScreen Object

Field	Type	Required	Description
headerMessage	string	❌	Header text for intro screen. Can be empty
mainMessage	string	❌	Main body text for intro screen. Can be empty
buttonMessage	string	❌	Custom text for start button. Can be empty
footnoteMessage	string	❌	Footer text for intro screen. Can be empty
customLogoUrl	string	❌	URL for custom logo on intro screen
inheritLogo	boolean	❌	Whether to inherit logo from namespace

customOutroScreen Object

Field	Type	Required	Description
outroMessage	string	❌	Message displayed on completion screen if hasCustomOutro is true

customCTA Object

Field	Type	Required	Description
ctaLink	string	❌	URL for call-to-action. Can be empty
ctaTitle	string	❌	Title for call-to-action (max 65 chars)
ctaButton	string	❌	Button text for CTA (max 50 chars)
ctaDescription	string	❌	Description text for CTA (max 320 chars)
sticky	boolean	❌	Whether CTA should be sticky

customRecommendationCard Object

This is where the recommendations live, and they can be customized. Each key in this object represents a card ID. The keys must be the following:

• fhn1
• fhn2
• fhn3
• fhn4
• fhn5
• fhn6
• fhn7
• fhn8

Empty text fields will have a default set value, except for the CTA links. The customRecommendationCard object has the following properties:

Field	Type	Required	Description
title	string	❌	Card title. Can be empty
subtitle	string	❌	Card subtitle. Can be empty
recommendationTitle	string	❌	Title for recommendations. Can be empty
recommendations	array	❌	Array of recommendation strings
CTA1Button	string	❌	Text for first CTA button. Can be empty
CTA1Link	string	❌	URL for first CTA. Can be empty
CTA2Button	string	❌	Text for second CTA button. Can be empty
CTA2Link	string	❌	URL for second CTA. Can be empty
CTA3Button	string	❌	Text for third CTA button. Can be empty
CTA3Link	string	❌	URL for third CTA. Can be empty

Example Request Body

{
  "name": "Employee Satisfaction Survey",
  "primaryColor": "#3366ff",
  "start": 1626246000000,
  "end": 1626417959999,
  "anonymous": true,
  "disableEmailing": true,
  "customIntroScreen": {
    "headerMessage": "Annual Employee Survey",
    "mainMessage": "Help us improve your workplace experience",
    "buttonMessage": "Start Survey"
  },
  "questions": [
    {
      "id": "fin_health",
      "required": true
    },
    {
      "id": "nps",
      "required": false
    }
  ]
}

---

Response

{
  "quiz": {
    "id": "sample-quiz",
    "name": "sample-quiz",
    "primaryColor": "#9b8163",
    "createdOn": 1626101719367,
    "start": 1626246000000,
    "end": 1626417959999,
    "questions": [... ],
    "anonymous": false,
    "status": "queued"
  }
}

---

Notes

• Demo namespaces and namespaces with a yearly quiz allocation have a limit on the number of quizzes that can be created
• The quiz is created with a status of "queued" and will become active at the specified start time