# About the Quiz API

The Quiz API manages quiz definitions used by quiz steps in Wix Online Programs. A definition contains quiz settings and its active questions, including the input type, answer key, feedback messages, and optional per-answer score. Creating or cloning a quiz definition requires at least one active question.

With the Quiz API, you can:

+ Create one or more quiz definitions.
+ Retrieve a quiz definition by ID.
+ Clone a definition for reuse in another developer-defined workflow.
+ Permanently delete one or more definitions.

## How quizzes relate to Online Programs

A quiz definition is separate from an Online Programs step. Creating or cloning a quiz doesn't add it to a program. To make the quiz available in a program:

1. Create or clone the quiz definition.
2. Read the new quiz ID from the response.
3. Create a quiz-type step with the Steps API and set `step.quizOptions.id` to the quiz ID.
4. Use the Quiz Submissions API to submit and evaluate participant answers.

The Quiz API intentionally doesn't provide a List or Query method. Discover an existing quiz ID by querying or retrieving its quiz-type step and reading `step.quizOptions.id`.

## Quiz definitions and submissions

Each item in `quiz.fields` defines one active question and its answer input. Creating or cloning a quiz requires at least one active question. A retrieved quiz can have an empty `fields` list after all its questions have been deleted. Check for active questions before displaying or reusing it.

When creating a definition, callers provide:

+ A stable question GUID in `fields.id`.
+ A stable submission key in `fields.target`. Quiz submissions use this key to match an answer to its question; it isn't the question's correct answer.
+ Exactly one input object, such as `numeric`, `shortText`, `longText`, `singleChoice`, `multiChoice`, or `fileUpload`.

New submissions are evaluated against the definition that exists when the submission is created. If a definition changes through another supported workflow, previously stored submissions retain their recorded grades and answer evaluations, while future submissions use the changed definition.

For single-choice questions, a supplied `rightAnswer` must exactly match an entry in `options`. For multi-choice questions, every supplied `rightAnswer` value must exactly match an entry in `options`. An answer key containing an unavailable option causes creation to fail with `INVALID_QUIZ`.

Existing image-choice questions from Wix Forms are returned as `multiChoice`, including questions whose original settings allow only one selection. The Quiz API doesn't expose image-choice-specific settings; the returned `multiChoice` shape doesn't establish that the original question allowed multiple selections.

See [Quiz Grading](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/quiz-grading) for matching, scoring, and attempt-limit behavior.

## Permissions and answer-key visibility

Callers with permission to create and clone quizzes can view their answer keys. Permission to retrieve a quiz alone doesn't grant access to its answer keys.

These rules apply to quiz definitions returned by the Quiz API. When the caller can't access answer keys, numeric, short-text, and single-choice `rightAnswer` fields are omitted, and multi-choice `rightAnswer` is an empty list. Questions, options, targets, IDs, and other metadata remain available.

Filtering affects responses only. It doesn't remove answers supplied in write requests, erase stored answer keys, or change server-side grading. An absent answer in a filtered response doesn't establish that the stored question has no correct answer. Don't use a filtered definition to reconstruct or overwrite answer keys.

Participants submit their own answers through the Quiz Submissions API. They don't need access to answer keys for server-side grading.

## Bulk operations and errors

An invalid quiz definition causes bulk creation to fail before any quizzes are created. Otherwise, a successful bulk request can still contain individual failures. Check each result's `itemMetadata.success` and `itemMetadata.error`, even when the request succeeds. Use `itemMetadata.originalIndex` to correlate results with inputs, and attach only successfully created quizzes to steps.

See [Bulk Create Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-create-quizzes) and [Bulk Delete Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-delete-quizzes) for request limits and response options.

Methods document errors such as `INVALID_QUIZ`, `QUIZ_NOT_FOUND`, and `QUIZ_CONFLICT`. Validation, authorization, temporary failures, and individual bulk results can return other error codes. Inspect the status and error details rather than handling only those three codes.

## Cloning

Cloning copies the quiz definition and returns a new quiz ID. It doesn't clone Online Programs step associations or quiz submissions. Attach the new ID to a step separately when needed.

Cloning requires a quiz with active questions. Avoid modifying the source quiz while cloning it. See [Clone Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/clone-quiz) for error details.

## Permanent deletion

`DeleteQuiz` and `BulkDeleteQuizzes` permanently delete quiz definitions. They don't check whether Online Programs steps reference those definitions. Coordinate deletion with the Steps API and remove known step references first. Otherwise, a step can retain a dangling quiz reference.

## Related APIs

+ [**Steps API**](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/steps): Attaches a quiz definition to a section in an Online Program and provides the supported path for discovering quiz IDs.
+ [**Quiz Submissions API**](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions): Accepts participant answers, evaluates them against the current quiz definition, and stores the resulting grade and per-answer evaluations.
+ [**Sections API**](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/sections): Supplies the parent section ID required when creating a step.

## Before you begin

It's important to note the following points before starting to code:

+ Install Wix Online Programs on the target site.
+ Obtain the parent section ID before creating a quiz step.
+ Generate stable, unique GUIDs for question `id` values and stable, unique `target` values within each quiz.
+ Provide a right answer for every question that should affect automatic grading.
+ Review [Quiz Grading](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/quiz-grading) before choosing passing grades or attempt limits. Non-evaluable answers count as correct, and question scores don't weight the earned-grade percentage.

## Use cases

+ Create a quiz, attach it to a program step, and evaluate participant answers, as described in [Sample Flows](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/sample-flows#add-a-quiz-assessment-to-a-program-step).

## Terminology

+ Quiz definition: The questions and settings that a participant's answers are evaluated against. Creating a definition doesn't attach it to a program step.
+ Quiz step: An Online Programs step that references a quiz definition through `quizOptions.id`.
+ Question target: The stable key that matches a submitted answer to a quiz question.
+ Answer key: A question's stored correct answer, distinct from its target and from a participant's submitted answer.
+ Quiz submission: A participant's answers and their recorded grade and answer evaluations.

## Examples

The cURL examples show REST requests and sample responses. The TypeScript examples use `quizzes` from `@wix/online-programs` and show sample SDK responses in `Promise resolves to` comments. Generate unique question GUIDs and replace sample quiz IDs with IDs returned by your own requests. SDK timestamps are JavaScript Dates, shown as ISO strings in the response comments.

Each method's reference page includes its request and response examples:

+ [Create Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/create-quiz)
+ [Get Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/get-quiz)
+ [Clone Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/clone-quiz)
+ [Bulk Create Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-create-quizzes)
+ [Delete Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/delete-quiz)
+ [Bulk Delete Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-delete-quizzes)

### REST and SDK field names

REST quiz and question IDs use `id`; the TypeScript SDK uses `_id`. Bulk result metadata follows the same convention: `itemMetadata.id` in REST and `itemMetadata._id` in the SDK. REST timestamps use `createdDate` and `updatedDate`; the SDK uses `_createdDate` and `_updatedDate`.

REST Create Quiz and Get Quiz responses wrap the definition in `quiz`. The SDK's `createQuiz()` and `getQuiz()` return the definition directly. SDK `cloneQuiz()` and `deleteQuiz()` responses retain the `quiz` wrapper.

@sdk_package_setup

# Quiz Grading

The Quiz Submissions API evaluates answers against the current quiz definition when a submission is created. It stores the resulting earned grade, passing grade, status, and per-answer evaluations on the submission.

## Answer matching

A submission's `answers` map uses each question's `target` as its key. Targets must remain stable and unique within the quiz. If a submitted target doesn't match a quiz question, the submission can't be evaluated.

Automatic matching depends on the question type:

| Question type | Matching behavior |
| --- | --- |
| Numeric | Exact numeric equality. |
| Short text | Leading and trailing whitespace is ignored, and comparison is case-insensitive. |
| Single choice | Exact equality with the configured option. |
| Multiple choice | Matches the configured correct options regardless of order. Duplicate values aren't ignored. |
| Long text | Not evaluated. |
| File upload | Not evaluated. |

## Missing answer keys and non-evaluable questions

A missing stored answer key is different from an answer key hidden in an API response. Hidden answer keys still participate in server-side grading. See [Permissions and answer-key visibility](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/introduction#permissions-and-answer-key-visibility) for details.

If a numeric, short-text, single-choice, or multiple-choice question has no stored right answer, its submitted answer is non-evaluable. Long-text and file-upload answers are always non-evaluable.

Non-evaluable answers count as correct when calculating `earnedGrade`. Provide a right answer for every automatically graded question, and account for long-text and file-upload questions when setting a passing grade.

## Earned grade and question scores

When `passingGrade` is configured, the earned grade is an unweighted integer percentage:

```text
earnedGrade = floor((answers counted as correct / submitted answers) * 100)
```

Each submitted answer has equal weight. For example, 2 correct answers out of 3 produce an earned grade of `66`, not `67`. A configured question `score` is returned for evaluable answers, whether correct or incorrect, but doesn't weight `earnedGrade` or determine pass/fail status. Non-evaluable answers omit `score`, `correct`, and feedback `message`; they still return the submitted value and question `fieldId`.

A submission is `FAILED` when its earned grade is lower than the configured passing grade. Otherwise, its status is `COMPLETED`.

If `passingGrade` is omitted, both `earnedGrade` and `passingGrade` are absent from the submission, and its status is `COMPLETED`, even if an individual evaluated answer is incorrect. Per-answer evaluation still takes place.

Submission status describes quiz evaluation only. It doesn't by itself mark the associated Online Programs step as completed. Use the [Resolved Steps API](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/resolved-steps/introduction) to record participant progress using the participant ID, program step ID, and quiz submission ID.

## Attempt limits

`settings.attempts` limits submissions per submitter. If omitted, the service doesn't apply an attempt-limit check.

Without a `groupId`, the count uses quiz ID and submitter ID. When a `groupId` is supplied, the count uses group ID and submitter ID without filtering by quiz ID. Reusing a group ID across quizzes therefore shares their attempt count, which is checked against the current quiz's `settings.attempts` limit.

Use the same `groupId` only for attempts that should share one limit. Don't reuse a program ID as the group ID for every quiz unless that shared count is intended.

## Definition changes

Every new submission uses the current quiz definition. Previously stored submissions keep the grade and answer evaluations recorded when they were created. As a result, attempts created before and after a definition change can reflect different questions, answer keys, or passing-grade settings.

# Quiz: Sample Flows

This article presents a possible use case and corresponding sample flow that you can support. It provides a useful starting point as you plan your implementation.

## Add a quiz assessment to a program step

An instructor creates a quiz for an Online Program, attaches it to a step, and lets a participant submit answers for evaluation. Creating a quiz definition alone doesn't add it to a program.

### Before you begin

- Install Wix Online Programs on the site and obtain an existing program section ID.
- For REST authoring calls, use an installed app's OAuth access token. See each method's reference for its authorization requirements.
- For participant submissions, use the logged-in member's OAuth access token, not the authoring app's token. The member must be the intended program participant.
- Follow the [REST API Authentication guide](fallback::https://dev.wix.com/docs/api-reference/articles/rest-authentication/rest-api-authentication) to obtain the appropriate tokens. Send the token in the `Authorization` header and keep app secrets on your backend.
- Generate stable question GUIDs and unique `target` values within the quiz. Submission answers use each question's target as the answer-map key.
- This flow supplies the answer key when creating the quiz and doesn't require reading it back. For details about hidden answer keys, see [Permissions and answer-key visibility](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/introduction#permissions-and-answer-key-visibility).

To add the assessment and evaluate a participant's answers:

1. Call [Create Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/create-quiz) with the question and quiz settings. For example:

   ```json
   {
     "quiz": {
       "settings": {
         "title": "European Capitals",
         "passingGrade": 70,
         "attempts": 3
       },
       "fields": [
         {
           "id": "11111111-1111-4111-8111-111111111111",
           "target": "capitalOfFrance",
           "question": "What is the capital of France?",
           "score": 1,
           "rightMessage": "Correct.",
           "wrongMessage": "Try again.",
           "singleChoice": {
             "rightAnswer": "Paris",
             "options": ["Paris", "Lyon", "Marseille"]
           }
         }
       ]
     }
   }
   ```

   Save the returned `quiz.id`. The ID supplied in `fields` identifies the question, not the quiz. Response filtering can hide the supplied answer key without changing the stored answer or grading.

2. Call the Steps API's [Create Step](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/steps/create-step) with the section ID and returned quiz ID:

   ```json
   {
     "step": {
       "sectionId": "<SECTION_ID>",
       "description": {
         "title": "European Capitals Quiz"
       },
       "stepType": "QUIZ",
       "quizOptions": {
         "id": "<QUIZ_ID>"
       }
     }
   }
   ```

   Save the returned step ID. The step's `quizOptions.id` is also the supported discovery path for the quiz ID.

3. Using participant authorization, call the Quiz Submissions API's [Create Quiz Submission](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions/create-quiz-submission). Use the question's target as the answer-map key:

   ```json
   {
     "submission": {
       "quizId": "<QUIZ_ID>",
       "answers": {
         "capitalOfFrance": {
           "value": "Paris"
         }
       }
     }
   }
   ```

   Read the submission's grade, status, and per-answer evaluations. The request omits `groupId`, so the attempt count is scoped to this quiz and submitter. Specify a stable group ID only when attempts should share a count across quizzes; see [Attempt limits](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/quiz-grading#attempt-limits).

### Record participant progress

Creating a submission evaluates answers but doesn't record completion of the program step. Use the [Resolved Steps API](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/resolved-steps/introduction) to record participant progress using the Online Programs participant ID, the step ID saved above, and the returned quiz submission ID.

### Create definitions in bulk

For a workflow with multiple quiz steps, use [Bulk Create Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-create-quizzes). Supply question IDs, but omit quiz-level IDs, revisions, and timestamps: supplied read-only values are ignored. Set `returnEntity` to `true` when you need the created definitions.

Invalid definitions fail the entire request before creation. A successful bulk request can still contain individual failures. Check each result's `itemMetadata.success` and inspect `itemMetadata.error` when it is `false`. Correlate results with input quizzes using `itemMetadata.originalIndex`. Attach only successful results to steps, using `itemMetadata.id` as the quiz ID.

### Find an existing quiz definition

The Quiz API doesn't list quiz definitions. To recover a quiz ID from a known section:

1. Call the Steps API's [Query Steps](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/steps/query-steps) with a `sectionId` filter. Continue paging if the needed step isn't in the first page.
2. Read `quizOptions.id` from the quiz-type step.
3. Call [Get Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/get-quiz) with that ID. Check for active questions before displaying or reusing the definition: a retrieved quiz can have no active questions even though creation and cloning require them.

### Clean up

Coordinate cleanup with the Steps workflow and remove known step references before permanently deleting a quiz. [Delete Quiz](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/delete-quiz) and [Bulk Delete Quizzes](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/bulk-delete-quizzes) don't perform a server-side shared-reference check. Deleting a referenced quiz can leave a dangling reference on a step.

## Related examples

See [Quiz API examples](fallback::https://dev.wix.com/docs/api-reference/business-management/online-programs/quizzes/introduction#examples) for links to individual requests and sample responses. The requests in this article are illustrative; replace sample IDs with IDs from your own program and quizzes.