Initialize Quiz

Initialize a quiz for a user and generate an empty answer object.

---

Overview

This endpoint creates an empty quiz answer object for the user and must be called before submitting any answers. The endpoint varies based on the quiz type.

Method: POST

Endpoints by Quiz Type

Quiz Type	Endpoint
Anonymous	/api/v1/namespaces/:namespaceId/quizzes/:quizId/users/anonymous/initQuiz
In-App	/api/v1/namespaces/:namespaceId/quizzes/:quizId/users/inapp/:sessionId/initQuiz
Invited	/api/v1/namespaces/:namespaceId/quizzes/:quizId/users/invited/:invitedUserUUID/initQuiz

See Quiz Types to understand the differences between anonymous, in-app, and invited quizzes.

---

Request

Path Parameters

Parameter	Type	Required	Quiz Type	Description
namespaceId	string	✅	All	Namespace unique ID
quizId	string	✅	All	Quiz unique ID
sessionId	string	✅	In-App	In-app session identifier
invitedUserUUID	string	✅	Invited	Invited user unique ID

Body Parameters

Field	Type	Required	Quiz Type	Description
anonymousUserId	string	✅	Anonymous	Anonymous user identifier (from Generate Anonymous User ID)
language	string	✅	All	Language code for questions (en for English, es for Spanish)
customParams	string	❌	All	Optional custom parameters, useful for tracking UTM tags or any custom data

Example Request Bodies

Anonymous

{
  "anonymousUserId": "anon_12345ABC",
  "language": "en",
  "customParams": "utm_source=newsletter"
}

In-App

{
  "language": "en",
  "customParams": "utm_source=app"
}

Invited

{
  "language": "en",
  "customParams": "utm_source=email"
}

---

Response

Example Responses

Anonymous

{
  "answers": {
    "id": "12345ABCD-anon1234",
    "userId": "anon1234",
    "quizId": "abc12345",
    "activityDate": {
      "_seconds": 1768503849,
      "_nanoseconds": 805000000
    },
    "qAnswers": {},
    "completionStatus": 1,
    "isAnonymous": true,
    "customData": ""
  },
  "anonymousUserId": "anon_12345ABC"
}

In-App

{
  "answers": {
    "id": "quizid1234-session1234",
    "userId": "session1234",
    "quizId": "quizid1234",
    "activityDate": {
      "_seconds": 1768504063,
      "_nanoseconds": 907000000
    },
    "qAnswers": {},
    "completionStatus": 1,
    "isAnonymous": false,
    "customData": ""
  }
}

Invited

{
  "answers": {
    "id": "12345ABCD-user1234",
    "userId": "user1234",
    "quizId": "abc12345",
    "activityDate": {
      "_seconds": 1768504488,
      "_nanoseconds": 170000000
    },
    "qAnswers": {},
    "completionStatus": 1,
    "isAnonymous": false,
    "customData": ""
  }
}

Response Fields

Field	Type	Description
id	string	Unique answer document ID (format: quizId-userId)
userId	string	User identifier
quizId	string	Quiz identifier
activityDate	object	Timestamp of initialization
qAnswers	object	Empty object (no answers submitted yet)
completionStatus	number	1 = initialized, 2 = in progress, 3 = completed
isAnonymous	boolean	true for anonymous quizzes, false for invited and in-app
customData	string	Custom data stored with the response
anonymousUserId	string	Returned only for anonymous quizzes

---

Error Responses

• 400 Bad Request – If the namespace has reached its response limit

{
  "error": "Limit of responses reached!"
}

• 400 Bad Request – If the quiz has ended

{
  "error": "quiz has ended",
  "errorCode": "quiz/ended"
}

• 400 Bad Request – If the quiz type doesn't match the endpoint (e.g., using anonymous endpoint for non-anonymous quiz)

{
  "error": "quiz only takes non anonymous submissions",
  "errorCode": "quiz/not_anonymous"
}

• 404 Not Found – If the namespace does not exist

{
  "error": "namespace not found",
  "errorCode": "namespace/not_found"
}

• 404 Not Found – If the quiz does not exist

{
  "error": "quiz not found",
  "errorCode": "quiz/not_found"
}

• 404 Not Found – If the invited user does not exist (for invited quizzes)

{
  "error": "user does not exist",
  "errorCode": "users/not_found"
}

• 403 Forbidden – If the invited user is not part of the quiz (for invited quizzes)

{
  "error": "user is not part of the quiz",
  "errorCode": "users/unauthorized"
}

• 422 Unprocessable Entity – If required parameters are missing or validation fails

{
  "validationErrors": {
    "body": {
      "language": {
        "message": "\"language\" is required"
      }
    }
  }
}