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 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.

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

1. Call Create Quiz with the question and quiz settings. For example:

   Copy

   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 with the section ID and returned quiz ID:

   Copy

   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. Use the question's target as the answer-map key:

   Copy

   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.

Record participant progress

Creating a submission evaluates answers but doesn't record completion of the program step. Use the Resolved Steps API 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. 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 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 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 and 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 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.