Skip to content

API: Quiz Plays endpoints

/quiz:results

GET /quiz:results:play

Get detailed results for a specific Quiz play.

[] Input:

  • [!] string play: Quiz play identification string

[] Output:

  • string play: Quiz play identification string
  • string user: user identification string
  • datetime time_start: start time
  • datetime time_end: end time
  • integer questions_total: total number of questions asked
  • integer questions_correct: number of correctly answered questions
  • float points_total: total points
  • float points_correct: total points scored
  • boolean valid: result is valid
    • finished successfully, all questions evaluated and not archived
  • boolean/null successful: attempt passed grading threshold (if applicable)
  • list questions
    • string index: question index
    • string/null id: external unique question identifier (if present)
    • string question: question identification string
    • float time_answer: number of seconds spent on question (if available)
    • float points_maximum: maximum points
    • float points: points scored

DELETE /quiz:results:play

Archive or forget the result of a Quiz play.

An exam result is archived: it disappears from the result lists and the reports of the exam, but it is kept and can be restored by adding the archived user back to the exam. A result outside of an exam is forgotten: the play is detached from the user and only kept for the statistics. Exam results can only be archived when archiving is enabled for the exam (see the archive setting of POST /exam:settings), and only the current result of the user can be archived. Results outside of an exam can only be forgotten by administrators.

[] Input:

  • [!] string play: Quiz play identification string

GET /quiz:results:user

Get user results for a specific Quiz set.

[] Input:

  • [!] string quiz: Quiz set identification string
  • [!] string user: user identification string

[] Output:

  • list results
    • string play: Quiz play identification string
    • string user: user identification string
    • datetime time_start: start time
    • datetime time_end: end time
    • integer questions_total: total number of questions asked
    • integer questions_correct: number of correctly answered questions
    • float points_total: total points
    • float points_correct: total points scored
    • boolean valid: result is valid
    • boolean/null successful: attempt passed grading threshold (if applicable)

/exam:results

GET /exam:results:user

Get user results for a specific exam.

[] Input:

  • [!] string exam: exam identification string
  • [!] string user: user identification string

[] Output:

  • list results
    • string play: Quiz play identification string
    • string user: user identification string
    • datetime time_start: start time
    • datetime time_end: end time
    • integer questions_total: total number of questions asked
    • integer questions_correct: number of correctly answered questions
    • float points_total: total points
    • float points_correct: total points scored
    • integer attempt: index of attempt
    • boolean valid: result is valid
    • boolean/null successful: attempt passed grading threshold (if applicable)

POST /exam:results:export

Generate a download link for the results of an exam. The generated link is not authenticated, so it can be handed over to any service, but it can only be used once and it expires in an hour. Only those examinees are exported that are visible for the current user, and the exported columns are controlled by the export settings of the exam (see GET /exam:settings). Exporting the results needs reporting permission for the exam.

[] Input:

  • [!] string exam: exam identification string
  • string format: format of the exported file
    • possible values: csv / xlsx
      • csv: semicolon separated values
      • xlsx: Excel 2007+ workbook
    • default: the export_format setting of the exam
  • string preset: content of the exported file
    • possible values: default / answers
      • default: the examinees with their results
      • answers: the answers only, without the examinees
    • the answers preset is only available for anonymous surveys
    • default: default
  • string sort: ordering of the examinees in the exported file
    • possible values: default / name
      • default: the same order they are listed in on the users page of the exam
      • name: by the name of the examinees
    • default: the export_sort setting of the exam
  • integer round: export the results of a previous round instead of the current one
    • only available when the exam is configured to keep the results of its previous rounds
    • has to be the number of an already closed round, see GET /exam:round
  • object filters: only export the examinees matching the given user data
    • keyed by the label of a custom user data field of the exam, see GET /exam:fields
    • only those select custom fields can be used that have their filtering configured
    • the value is one of the filterable options of the field, or a list of them
    • the examinees have to match any of the values given for the same field, and all of the fields specified
    • cannot be combined with round, the results of a previous round cannot be filtered
  • string language: language of the exported file
    • default: the language of the user

[] Output:

  • string exam: exam identification string
  • string format: format of the exported file
  • string[url] url: download link for the results
  • datetime valid: date and time of link expiration

/exam:certificates

GET /exam:certificates:user

Get (the latest) certificate details for a specific exam and user.

[] Input:

  • [!] string exam: exam identification string
  • [!] string user: user identification string

[] Output:

  • string play: Quiz play identification string
  • string user: user identification string
  • boolean archived: exam result is archived
  • boolean eligible: result is eligible for certification
  • boolean certified: result is eligible for certification and also certified
  • string serial: serial number of the certificate (only present if the result is certified and serial numbering is enabled)
  • date expires: date of expiration (only present if the result is certified and expiration is configured)

POST /exam:certificates:user:download

Generate download link for the latest user exam certificate. If a previous valid link exists, it will be returned instead.

[] Input:

  • [!] string exam: exam identification string
  • [!] string user: user identification string

[] Output:

  • string play: Quiz play identification string
  • string user: user identification string
  • string[url] url: download link for the certificate
  • date valid: date of link expiration