Quiz Submissions API: Sample Flows

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

For authentication, answer formats, and grading behavior, see Introduction.

The flows below use REST response field names. With the JavaScript SDK, Create and Get return the submission directly, while Delete returns an object containing quizSubmission. Read the submission ID from _id instead of id. See SDK examples.

Submit answers and display the result

Build a custom quiz experience that displays feedback after a participant submits their answers.

To submit answers and display the result:

1. Call Get Step with the program-step ID and read the quiz ID from step.quizOptions.id.
2. Call Get Quiz to retrieve the question targets and answer options.
3. Call Create Quiz Submission with quizSubmission.quizId and quizSubmission.answers. Key each answer by its question target. For a single-choice question, send the exact option value selected by the participant.
4. Save the returned quizSubmission.id. Display the result using evaluationStatus, answers, and, when present, earnedGrade and passingGrade.

Use the participant's signed-in member identity when submitting their answers. In a headless client, complete member authentication and use the resulting member token or authenticated SDK client. App authentication doesn't impersonate a participant. Creating a submission evaluates the answers but doesn't record program-step progress.

Retrieve a saved result

Display a participant's stored answers and evaluation when they return to your quiz experience. Retain the submission ID from creation rather than assuming every historical attempt remains available.

To display a saved result:

1. Call Get Quiz Submission with the saved quiz-submission ID.
2. Read quizSubmission.answers, quizSubmission.evaluationStatus, and any grading fields to display the result.

Remove an unwanted attempt

Let an authorized caller discard an unwanted quiz attempt without resetting the participant's program-step progress.

To remove the attempt:

1. Call Delete Quiz Submission with the quiz-submission ID you intend to remove.
2. Use the returned quizSubmission if you need the attempt's data from before deletion.

Deleting a submission doesn't reset program-step progress.

Record or reset program progress

To associate a quiz attempt with a participant's step or reset their recorded progress, see the Resolved Steps API.