> 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 # CreateQuizSubmission # Package: onlinePrograms # Namespace: QuizSubmissionsService # Method link: https://dev.wix.com/docs/api-reference/business-management/online-programs/quiz-submissions/create-quiz-submission.md ## Permission Scopes: Manage Online Programs: SCOPE.CHALLENGES.MANAGE ## Introduction Submits quiz answers and returns their evaluation results. Specify `quizSubmission` and `quizSubmission.quizId`. The `answers` map can be empty when no questions require answers. Otherwise, provide answers keyed by the quiz questions' targets. The submitter is derived from the caller's authentication context. The API does not accept or return a submitter field. If the quiz defines an attempt limit, creation fails with FAILED_PRECONDITION when the submitter's existing attempts reach that limit. Attempts are counted by groupId when supplied, otherwise by quizId. No attempt limit is enforced by this operation when the quiz has no configured limit. Invalid quiz configuration or an unrecognized answer target also causes FAILED_PRECONDITION, reported as "Quiz is not configured" rather than "Quiz submissions exceed attempts limit". Do not infer exhausted attempts from the status alone. For a configuration or target error, refresh the quiz definition and verify the submitted target keys before retrying. Use `evaluationStatus` for the evaluation result. A `COMPLETED` evaluation result doesn't by itself resolve the associated program step. To record program progress, see the [Resolved Steps API](https://dev.wix.com/docs/api-reference/business-management/online-programs/resolved-steps/introduction.md). Caller-supplied extendedFields are stored with the quiz submission and returned by Create, Get, and Delete Quiz Submission, subject to Data Extensions schema and access permissions. --- ## REST API ### Schema ``` Method: createQuizSubmission Description: Submits quiz answers and returns their evaluation results. Specify `quizSubmission` and `quizSubmission.quizId`. The `answers` map can be empty when no questions require answers. Otherwise, provide answers keyed by the quiz questions' targets. The submitter is derived from the caller's authentication context. The API does not accept or return a submitter field. If the quiz defines an attempt limit, creation fails with FAILED_PRECONDITION when the submitter's existing attempts reach that limit. Attempts are counted by groupId when supplied, otherwise by quizId. No attempt limit is enforced by this operation when the quiz has no configured limit. Invalid quiz configuration or an unrecognized answer target also causes FAILED_PRECONDITION, reported as "Quiz is not configured" rather than "Quiz submissions exceed attempts limit". Do not infer exhausted attempts from the status alone. For a configuration or target error, refresh the quiz definition and verify the submitted target keys before retrying. Use `evaluationStatus` for the evaluation result. A `COMPLETED` evaluation result doesn't by itself resolve the associated program step. To record program progress, see the [Resolved Steps API](https://dev.wix.com/docs/api-reference/business-management/online-programs/resolved-steps/introduction.md). Caller-supplied extendedFields are stored with the quiz submission and returned by Create, Get, and Delete Quiz Submission, subject to Data Extensions schema and access permissions. URL: https://www.wixapis.com/online-programs/v1/quiz-submissions Method: POST Method parameters: param name: quizSubmission | type: QuizSubmission | description: Answers submitted to a quiz within an Online Program, together with their evaluation results. - name: quizId | type: string | description: Quiz GUID. | validation: format GUID - name: groupId | type: string | description: Groups attempts for the same submitter when enforcing the quiz's attempt limit. If omitted, attempts are counted by quizId and submitter, and groupId remains absent in the response. If provided, counting uses groupId and submitter without restricting by quizId. | validation: format GUID - name: answers | type: Map | description: Answers keyed by each quiz question's target, not its field GUID. Each response answer includes the corresponding fieldId. An unrecognized target causes submission creation to fail. | validation: format map - name: value | type: Value | description: Submitted answer value, with a JSON shape determined by the question type: - Short text and long text: a string. - Single choice: the exact selected string from the question's singleChoice.options. - Numeric: a number. - Multiple choice: an array of exact selected strings from the question's multiChoice.options. - File upload: an array of file descriptor objects containing fileId, displayName, and fileType (MIME type), with url when supplied by the upload result. Submit uploaded-file metadata, not raw file bytes or an array of URL strings. Choice option strings also serve as their labels. Do not submit option GUIDs or independently translated or otherwise modified display text. Short-text comparison ignores surrounding whitespace and letter case; multiple-choice comparison ignores order but retains duplicates. Long-text and file-upload answers are stored but are not evaluated for correctness. Short-text, numeric, single-choice, and multiple-choice answers are also non-evaluable when the question has no stored correct-answer key. Such answers count as correct when calculating earnedGrade, but omit correct, score, and message in the response. A correct-answer key hidden from a caller's Quiz response is not necessarily absent from the stored quiz and does not establish that the answer is non-evaluable. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: extendedFields | type: ExtendedFields | description: Custom field data for the quiz submission. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Set extendedFields when creating a submission; Create, Get, and Delete return the stored values, subject to Data Extensions schema and access permissions. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map Return type: CreateQuizSubmissionResponse - name: quizSubmission | type: QuizSubmission | description: Created quiz submission. - name: id | type: string | description: Quiz submission GUID. | read-only: true | validation: format GUID - name: quizId | type: string | description: Quiz GUID. | validation: format GUID - name: groupId | type: string | description: Groups attempts for the same submitter when enforcing the quiz's attempt limit. If omitted, attempts are counted by quizId and submitter, and groupId remains absent in the response. If provided, counting uses groupId and submitter without restricting by quizId. | validation: format GUID - name: earnedGrade | type: integer | description: Integer percentage of submitted answers evaluated as correct, rounded down. Non-evaluable answers count as correct, including answers to questions without a stored correct-answer key. Question scores are not used as weights. Omitted when the quiz has no passing grade. | read-only: true | validation: format int32 - name: passingGrade | type: integer | description: Passing-grade threshold copied from the quiz settings when the submission is created. Compared with earnedGrade on the same percentage scale. Omitted if the quiz has no passing grade; later quiz-setting changes do not recalculate this submission. | read-only: true | validation: format int32 - name: answers | type: Map | description: Answers keyed by each quiz question's target, not its field GUID. Each response answer includes the corresponding fieldId. An unrecognized target causes submission creation to fail. | validation: format map - name: value | type: Value | description: Submitted answer value, with a JSON shape determined by the question type: - Short text and long text: a string. - Single choice: the exact selected string from the question's singleChoice.options. - Numeric: a number. - Multiple choice: an array of exact selected strings from the question's multiChoice.options. - File upload: an array of file descriptor objects containing fileId, displayName, and fileType (MIME type), with url when supplied by the upload result. Submit uploaded-file metadata, not raw file bytes or an array of URL strings. Choice option strings also serve as their labels. Do not submit option GUIDs or independently translated or otherwise modified display text. Short-text comparison ignores surrounding whitespace and letter case; multiple-choice comparison ignores order but retains duplicates. Long-text and file-upload answers are stored but are not evaluated for correctness. Short-text, numeric, single-choice, and multiple-choice answers are also non-evaluable when the question has no stored correct-answer key. Such answers count as correct when calculating earnedGrade, but omit correct, score, and message in the response. A correct-answer key hidden from a caller's Quiz response is not necessarily absent from the stored quiz and does not establish that the answer is non-evaluable. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: fieldId | type: string | description: GUID of the quiz question corresponding to this answer's target key. Returned as evaluation metadata; do not use this GUID as the answers map key. | read-only: true | validation: format GUID - name: score | type: number | description: Score configured for an evaluable question. Returned whether the answer is correct or incorrect; not used as a weight when calculating earnedGrade. Omitted for non-evaluable answers. | read-only: true | validation: format double - name: correct | type: boolean | description: Whether the answer matches the question's configured correct answer. Omitted for long-text and file-upload questions, and for otherwise evaluable questions without a stored correct-answer key. An omitted value does not mean the answer is incorrect. | read-only: true - name: message | type: string | description: Configured feedback for a correct or incorrect answer, selected according to the evaluation result. Omitted for non-evaluable answers. | read-only: true | validation: maxLength 350 - name: createdDate | type: string | description: Date and time the quiz submission was created. | read-only: true | validation: format date-time - name: updatedDate | type: string | description: Date and time the quiz submission was last updated. | read-only: true | validation: format date-time - name: revision | type: string | description: Revision number of the backing form submission. Increases when that submission is updated. | read-only: true | validation: format int64 - name: extendedFields | type: ExtendedFields | description: Custom field data for the quiz submission. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Set extendedFields when creating a submission; Create, Get, and Delete return the stored values, subject to Data Extensions schema and access permissions. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: evaluationStatus | type: EvaluationStatus | description: Stored evaluation result. An unspecified value must not be treated as failure or completion. | read-only: true - enum: - FAILED: Earned grade is below the passing grade. - COMPLETED: Earned grade meets or exceeds the passing grade, or no passing grade is configured. ``` ### Examples ### Submit quiz answers Submits a single-choice answer to a quiz with a 70% passing grade. The answer must match an option value in the quiz. ```curl curl --request POST \ "https://www.wixapis.com/online-programs/v1/quiz-submissions" \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ --data '{ "quizSubmission": { "quizId": "7f5c1d92-a638-4e0b-9c24-6d8b312f704a", "answers": { "capitalOfFrance": { "value": "Paris" } } } }' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.onlinePrograms.quizSubmissions.createQuizSubmission(options) Description: Submits quiz answers and returns their evaluation results. Specify `quizSubmission` and `quizSubmission.quizId`. The `answers` map can be empty when no questions require answers. Otherwise, provide answers keyed by the quiz questions' targets. The submitter is derived from the caller's authentication context. The API does not accept or return a submitter field. If the quiz defines an attempt limit, creation fails with FAILED_PRECONDITION when the submitter's existing attempts reach that limit. Attempts are counted by groupId when supplied, otherwise by quizId. No attempt limit is enforced by this operation when the quiz has no configured limit. Invalid quiz configuration or an unrecognized answer target also causes FAILED_PRECONDITION, reported as "Quiz is not configured" rather than "Quiz submissions exceed attempts limit". Do not infer exhausted attempts from the status alone. For a configuration or target error, refresh the quiz definition and verify the submitted target keys before retrying. Use `evaluationStatus` for the evaluation result. A `COMPLETED` evaluation result doesn't by itself resolve the associated program step. To record program progress, see the [Resolved Steps API](https://dev.wix.com/docs/api-reference/business-management/online-programs/resolved-steps/introduction.md). Caller-supplied extendedFields are stored with the quiz submission and returned by Create, Get, and Delete Quiz Submission, subject to Data Extensions schema and access permissions. Method parameters: param name: options | type: CreateQuizSubmissionOptions none - name: quizSubmission | type: QuizSubmission | description: Quiz submission to create. - name: quizId | type: string | description: Quiz GUID. | validation: format GUID - name: groupId | type: string | description: Groups attempts for the same submitter when enforcing the quiz's attempt limit. If omitted, attempts are counted by quizId and submitter, and groupId remains absent in the response. If provided, counting uses groupId and submitter without restricting by quizId. | validation: format GUID - name: answers | type: Map | description: Answers keyed by each quiz question's target, not its field GUID. Each response answer includes the corresponding fieldId. An unrecognized target causes submission creation to fail. | validation: format map - name: value | type: Value | description: Submitted answer value, with a JSON shape determined by the question type: - Short text and long text: a string. - Single choice: the exact selected string from the question's singleChoice.options. - Numeric: a number. - Multiple choice: an array of exact selected strings from the question's multiChoice.options. - File upload: an array of file descriptor objects containing fileId, displayName, and fileType (MIME type), with url when supplied by the upload result. Submit uploaded-file metadata, not raw file bytes or an array of URL strings. Choice option strings also serve as their labels. Do not submit option GUIDs or independently translated or otherwise modified display text. Short-text comparison ignores surrounding whitespace and letter case; multiple-choice comparison ignores order but retains duplicates. Long-text and file-upload answers are stored but are not evaluated for correctness. Short-text, numeric, single-choice, and multiple-choice answers are also non-evaluable when the question has no stored correct-answer key. Such answers count as correct when calculating earnedGrade, but omit correct, score, and message in the response. A correct-answer key hidden from a caller's Quiz response is not necessarily absent from the stored quiz and does not establish that the answer is non-evaluable. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: extendedFields | type: ExtendedFields | description: Custom field data for the quiz submission. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Set extendedFields when creating a submission; Create, Get, and Delete return the stored values, subject to Data Extensions schema and access permissions. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map Return type: PROMISE - name: _id | type: string | description: Quiz submission GUID. | read-only: true | validation: format GUID - name: quizId | type: string | description: Quiz GUID. | validation: format GUID - name: groupId | type: string | description: Groups attempts for the same submitter when enforcing the quiz's attempt limit. If omitted, attempts are counted by quizId and submitter, and groupId remains absent in the response. If provided, counting uses groupId and submitter without restricting by quizId. | validation: format GUID - name: earnedGrade | type: integer | description: Integer percentage of submitted answers evaluated as correct, rounded down. Non-evaluable answers count as correct, including answers to questions without a stored correct-answer key. Question scores are not used as weights. Omitted when the quiz has no passing grade. | read-only: true | validation: format int32 - name: passingGrade | type: integer | description: Passing-grade threshold copied from the quiz settings when the submission is created. Compared with earnedGrade on the same percentage scale. Omitted if the quiz has no passing grade; later quiz-setting changes do not recalculate this submission. | read-only: true | validation: format int32 - name: answers | type: Map | description: Answers keyed by each quiz question's target, not its field GUID. Each response answer includes the corresponding fieldId. An unrecognized target causes submission creation to fail. | validation: format map - name: value | type: Value | description: Submitted answer value, with a JSON shape determined by the question type: - Short text and long text: a string. - Single choice: the exact selected string from the question's singleChoice.options. - Numeric: a number. - Multiple choice: an array of exact selected strings from the question's multiChoice.options. - File upload: an array of file descriptor objects containing fileId, displayName, and fileType (MIME type), with url when supplied by the upload result. Submit uploaded-file metadata, not raw file bytes or an array of URL strings. Choice option strings also serve as their labels. Do not submit option GUIDs or independently translated or otherwise modified display text. Short-text comparison ignores surrounding whitespace and letter case; multiple-choice comparison ignores order but retains duplicates. Long-text and file-upload answers are stored but are not evaluated for correctness. Short-text, numeric, single-choice, and multiple-choice answers are also non-evaluable when the question has no stored correct-answer key. Such answers count as correct when calculating earnedGrade, but omit correct, score, and message in the response. A correct-answer key hidden from a caller's Quiz response is not necessarily absent from the stored quiz and does not establish that the answer is non-evaluable. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: fieldId | type: string | description: GUID of the quiz question corresponding to this answer's target key. Returned as evaluation metadata; do not use this GUID as the answers map key. | read-only: true | validation: format GUID - name: score | type: number | description: Score configured for an evaluable question. Returned whether the answer is correct or incorrect; not used as a weight when calculating earnedGrade. Omitted for non-evaluable answers. | read-only: true - name: correct | type: boolean | description: Whether the answer matches the question's configured correct answer. Omitted for long-text and file-upload questions, and for otherwise evaluable questions without a stored correct-answer key. An omitted value does not mean the answer is incorrect. | read-only: true - name: message | type: string | description: Configured feedback for a correct or incorrect answer, selected according to the evaluation result. Omitted for non-evaluable answers. | read-only: true | validation: maxLength 350 - name: _createdDate | type: Date | description: Date and time the quiz submission was created. | read-only: true - name: _updatedDate | type: Date | description: Date and time the quiz submission was last updated. | read-only: true - name: revision | type: string | description: Revision number of the backing form submission. Increases when that submission is updated. | read-only: true | validation: format int64 - name: extendedFields | type: ExtendedFields | description: Custom field data for the quiz submission. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. Set extendedFields when creating a submission; Create, Get, and Delete return the stored values, subject to Data Extensions schema and access permissions. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). | validation: format map - name: evaluationStatus | type: EvaluationStatus | description: Stored evaluation result. An unspecified value must not be treated as failure or completion. | read-only: true - enum: - FAILED: Earned grade is below the passing grade. - COMPLETED: Earned grade meets or exceeds the passing grade, or no passing grade is configured. ``` ### Examples ### Submit quiz answers ```javascript import { quizSubmissions } from "@wix/online-programs"; // Single-choice answers must match an option value in the quiz. const createdQuizSubmission = await quizSubmissions.createQuizSubmission({ quizSubmission: { quizId: "7f5c1d92-a638-4e0b-9c24-6d8b312f704a", answers: { capitalOfFrance: { value: "Paris" } } } }); /* Response excerpt: { "quizId": "7f5c1d92-a638-4e0b-9c24-6d8b312f704a", "earnedGrade": 100, "passingGrade": 70, "answers": { "capitalOfFrance": { "value": "Paris", "fieldId": "e81b49d6-25a3-4f72-b908-1c6d530ae247", "score": 1, "correct": true, "message": "Correct." } }, "revision": "1", "evaluationStatus": "COMPLETED", "_id": "c42a6e83-18b7-49d5-a602-93f1bd807e4c", "_createdDate": new Date("2026-09-21T10:32:08.421Z"), "_updatedDate": new Date("2026-09-21T10:32:08.586Z") } */ ``` ### createQuizSubmission (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { quizSubmissions } from '@wix/online-programs'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { quizSubmissions }, // Include the auth strategy and host as relevant }); async function createQuizSubmission(options) { const response = await myWixClient.quizSubmissions.createQuizSubmission(options); }; ``` ---