This article explains answer formats, attempt limits, grading, access rules, and submission history. For an overview and prerequisites, see About the Quiz Submissions API.
| 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.
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 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.
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.
Upload the file before submitting the quiz answer. For an app-managed upload, call Generate File Upload URL 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:
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.
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.
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.
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.
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.
See Sample Flows 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.
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.
Last updated: 22 September 2026