> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Quiz Submission Behavior

## Article: Quiz Submission Behavior

## Article Link: https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions/quiz-submission-behavior.md

## Article Content:

# Quiz Submission Behavior

This article explains answer formats, attempt limits, grading, access rules, and submission history. For an overview and prerequisites, see [About the Quiz Submissions API](https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions/introduction.md).

## Operations

| Operation | Use it to | Response entity field |
| --- | --- | --- |
| Create Quiz Submission | Submit and evaluate one attempt | `quizSubmission` |
| Get Quiz Submission | Retrieve a stored attempt by its ID | `quizSubmission` |
| Delete Quiz Submission | Remove an unwanted attempt | `quizSubmission` (the data before deletion) |

Specify `quizSubmission` when creating an attempt and read `quizSubmission` from REST responses. There is no public operation in this surface for updating answers or listing all attempts.

## Submitting answers

Create a submission with the required `quizSubmission` object and `quizSubmission.quizId`. Supply answers in an `answers` map; the map can be empty when no questions require answers. Each map key is the question's target, not its field ID. The response includes the question's `fieldId` alongside the submitted value and available evaluation details.

Submission ownership is derived from the caller's authentication context. The API does not accept or return a `submitter` field. An integration authenticated as an app must not assume that submissions will be attributed to a participant.

### Access to stored submissions

Access to retrieve and delete submissions is checked separately. Site members with access limited to their own submissions receive `NOT_FOUND` when requesting another member's submission. Callers with site-wide access can work with submissions from other submitters on the same site.

### Answer value formats

Each entry in `answers` contains a `value`:

| Question type | `value` format |
| --- | --- |
| Short text or long text | String |
| Numeric | Number |
| Single choice | Exact selected string from the question's `singleChoice.options` |
| Multiple choice | Array of exact selected strings from the question's `multiChoice.options` |
| File upload | Array of file descriptor objects with `fileId`, `displayName`, and `fileType` (MIME type), plus `url` when supplied by the upload result |

Choice option strings also serve as their labels. Submit the exact strings from the quiz definition, not option IDs or independently translated or otherwise modified display text. File uploads use uploaded-file metadata rather than raw bytes or URL strings. Long-text and file-upload answers are stored but are not evaluated for correctness.

### Submit a file-upload answer

Upload the file before submitting the quiz answer. For an app-managed upload, call [Generate File Upload URL](https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/generate-file-upload-url.md) from a backend authenticated as a Wix app or Wix user, then follow the upload instructions linked from that method. Generating an upload URL doesn't upload the file. Wait until the uploaded file is ready before using it in an answer.

Map the uploaded file's ID, display name, and MIME type into the answer value. For example, if the question target is `assignmentFile`:

```json
{
  "answers": {
    "assignmentFile": {
      "value": [
        {
          "fileId": "b29c874e-2e0f-49bd-a81c-68be9d473705",
          "displayName": "assignment.pdf",
          "fileType": "application/pdf"
        }
      ]
    }
  }
}
```

Replace the illustrative file ID with the actual uploaded file ID, which isn't necessarily a UUID. Include `url` when supplied by the upload result. This object is part of `quizSubmission`; it isn't a complete Create request. Submit metadata, not the upload URL or raw file bytes. Uploading with an app identity doesn't change the identity used for the separate quiz-submission call.

## Attempts and grading

Quiz settings can limit the number of attempts. When a limit is configured, creation fails after the submitter reaches it. Attempts are counted by submitter and `groupId`, or by submitter and quiz ID if `groupId` is omitted. Supplying the same group ID across quizzes shares the attempt-counting group. Omitting `groupId` does not populate it in the response.

When a passing grade is configured, `earnedGrade` is the percentage of submitted answers evaluated as correct, rounded down. Non-evaluable answers count as correct for this calculation. Individual question scores are not used as weights. The passing-grade threshold is stored with the submission and is not recalculated when quiz settings change.

Short-text, numeric, single-choice, and multiple-choice answers are also non-evaluable when their question has no stored correct-answer key. These answers count as correct in `earnedGrade`, just like other non-evaluable answers, and omit `correct`, `score`, and `message` in the response. An omitted `correct` value does not mean the answer is incorrect.

This behavior depends on the stored quiz configuration. A correct-answer key hidden from the caller's Quiz response is not necessarily missing from storage, so its absence in that response does not establish that grading is disabled.

Without a configured passing grade, `evaluationStatus` is `COMPLETED` and `earnedGrade` is omitted. A completed evaluation does not by itself mean that the associated program step has been resolved.

### Submission status

Read `evaluationStatus` for the submission's result:

- `UNKNOWN_EVALUATION_STATUS` (`0`): Unspecified; not an implemented evaluation outcome. Do not treat it as completion.
- `FAILED` (`1`): The earned grade is below the passing grade.
- `COMPLETED` (`2`): The earned grade meets the passing grade, or no passing grade is configured.

Create, Get, and Delete populate this field from the stored evaluation result.

A completed submission does not by itself mean the participant's program step has been resolved.

## Program progress and submission history

Submission creation and program-step resolution are distinct operations. Use the program-step resolution workflow with the created submission ID. Likewise, deleting a submission does not directly undo a resolved step; use the step-undo workflow to reset participant progress.

Removing a resolved step or clearing its linked submission can trigger deletion of that submission. Resolving a step with a submission can also remove other submissions for the same member and quiz. Do not treat this API as a permanent archive of every attempt.

Get Quiz Submission requires an existing submission ID. Retain the ID returned by creation. For submissions linked to resolved steps, the step's `quizSubmissionId` identifies the corresponding submission. This does not provide discovery of every unlinked attempt.

## Handling unsuccessful requests

Create Quiz Submission uses `FAILED_PRECONDITION` for more than one failure condition. Do not interpret the status alone as exhausted attempts:

| Reported error | Condition | What to check |
| --- | --- | --- |
| `Quiz submissions exceed attempts limit` | The existing attempt count reaches the configured limit. | Check the quiz's attempt settings and the submitter's counting group. Repeating the same request does not resolve an exhausted limit. |
| `Quiz is not configured` | The quiz configuration is invalid, or a submitted answer target cannot be matched to a quiz question. | Refresh the quiz definition and verify its configuration and the submitted question targets before retrying. Use target strings, not question field IDs, as the answer keys. |

Retrying Create after a timeout can create another attempt. Retain a returned submission ID as soon as it's available; don't automatically retry an ambiguous result.

## Examples and workflows

See [Sample Flows](https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions/sample-flows.md) for submitting answers, retrieving results, and removing attempts. The Create, Get, and Delete examples use `https://www.wixapis.com/online-programs/v1/quiz-submissions`. Replace the sample IDs, question target, and answer with values for your quiz, and use an authorized identity. Use a member's authenticated context to create that member's submission; app authentication doesn't impersonate a participant.

The examples demonstrate an app-owned submission when run with app authentication. To create a participant's submission, use that member's authenticated context instead. See [member authentication](https://dev.wix.com/docs/go-headless/authentication/about-authentication.md#member-authentication).

### SDK examples

Import `quizSubmissions` from `@wix/online-programs`. Pass the entity in the `quizSubmission` property of the options object when calling `createQuizSubmission()`.

Create and Get return the quiz-submission entity directly. Delete returns an object containing `quizSubmission`. SDK entities use `_id` for the submission ID and JavaScript `Date` values for `_createdDate` and `_updatedDate`. The `revision` value is a string.