The Quiz Submissions API evaluates answers against the current quiz definition when a submission is created. It stores the resulting earned grade, passing grade, status, and per-answer evaluations on the submission.
A submission's answers map uses each question's target as its key. Targets must remain stable and unique within the quiz. If a submitted target doesn't match a quiz question, the submission can't be evaluated.
Automatic matching depends on the question type:
| Question type | Matching behavior |
|---|---|
| Numeric | Exact numeric equality. |
| Short text | Leading and trailing whitespace is ignored, and comparison is case-insensitive. |
| Single choice | Exact equality with the configured option. |
| Multiple choice | Matches the configured correct options regardless of order. Duplicate values aren't ignored. |
| Long text | Not evaluated. |
| File upload | Not evaluated. |
A missing stored answer key is different from an answer key hidden in an API response. Hidden answer keys still participate in server-side grading. See Permissions and answer-key visibility for details.
If a numeric, short-text, single-choice, or multiple-choice question has no stored right answer, its submitted answer is non-evaluable. Long-text and file-upload answers are always non-evaluable.
Non-evaluable answers count as correct when calculating earnedGrade. Provide a right answer for every automatically graded question, and account for long-text and file-upload questions when setting a passing grade.
When passingGrade is configured, the earned grade is an unweighted integer percentage:
Each submitted answer has equal weight. For example, 2 correct answers out of 3 produce an earned grade of 66, not 67. A configured question score is returned for evaluable answers, whether correct or incorrect, but doesn't weight earnedGrade or determine pass/fail status. Non-evaluable answers omit score, correct, and feedback message; they still return the submitted value and question fieldId.
A submission is FAILED when its earned grade is lower than the configured passing grade. Otherwise, its status is COMPLETED.
If passingGrade is omitted, both earnedGrade and passingGrade are absent from the submission, and its status is COMPLETED, even if an individual evaluated answer is incorrect. Per-answer evaluation still takes place.
Submission status describes quiz evaluation only. It doesn't by itself mark the associated Online Programs step as completed. Use the Resolved Steps API to record participant progress using the participant ID, program step ID, and quiz submission ID.
settings.attempts limits submissions per submitter. If omitted, the service doesn't apply an attempt-limit check.
Without a groupId, the count uses quiz ID and submitter ID. When a groupId is supplied, the count uses group ID and submitter ID without filtering by quiz ID. Reusing a group ID across quizzes therefore shares their attempt count, which is checked against the current quiz's settings.attempts limit.
Use the same groupId only for attempts that should share one limit. Don't reuse a program ID as the group ID for every quiz unless that shared count is intended.
Every new submission uses the current quiz definition. Previously stored submissions keep the grade and answer evaluations recorded when they were created. As a result, attempts created before and after a definition change can reflect different questions, answer keys, or passing-grade settings.
Last updated: 22 September 2026