Pearson
Always Learning

API Group: 

This guide describes the API sequence for a user starting an exam for the first time or if the exam had been reset (the entire exam history was deleted for that user).

  • If the user is retaking a previously completed exam, see the Retake Exam How-To Guide.
  • If the user was interrupted and is completing a previously started exam in a new session, see the Continue Exam How-To Guide.

The following sequence maps the parallel processes between the typical actions of a user taking an exam and the Exam resources performing the processing. Click the resource link to open its detailed description.

Note: The following use case supports retrieving the entire set of questions for the exam before the user answers any questions. This scenario supports presenting multiple questions on a UI single page. Optionally, a single question can be retrieved and its answer can be saved before the next question is retrieved. Just be sure to repeat this process for each question in a section and each section in the exam.

Important: An exam cannot be started using the LearningStudio user interface and then modified or completed using the Exam API. If the exam is started using the LearningStudio UI, it must be completed using the UI.


User Interface API Notes
User opens exam. 1. (Optional) Get the system time from the LearningStudio server to coordinate durations.

GET /systemDateTime

 

2. Get the array of exam IDs from course items. If the specific exam ID is known, skip this step.

GET /users/{userId}/courses/{courseId}/items

User starts exam. 3. Create exam instance (aka "provision exam") for user.

POST /users/{userId}/courses/{courseId}/exams/{examId}

  • Provisioning exams are allowed only between the scheduled start and end date/times of exam.
  • Do create exam instance only once per user ID per exam ID. An error code of 400 (Bad Request) is returned if a POST is reattempted while an exam is open for a user (for example, exam has not been completed or deleted).
  • Until the user ID is posted to the exam ID, the contents of the exam cannot be retrieved.
4. Create attempts instance where user answers are stored.

POST /users/{userId}/courses/{courseId}/exams/{examId}/attempts

 

  • Do create attempts instance only once per user ID per exam ID. If a POST is reattempted with an attempts instance whose isCompleted attribute is still set to False, an error code is returned.
  • Response body includes attempt ID and pearsonExamToken.
  • The Pearson-Exam-Token token must be included in the request header in all further transactions for the attempts instance.
  • Exam duration begins on the LearningStudio server ("clock starts").
5. Get exam structure.

 

  a. Get array of sections within exam.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections

 

  b. Get array of questions for each section. Repeat for each section in exam.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/questions

Optionally, the question count, question types, and total number of possible points can be displayed to the user.
6. Get exam contents (data and choices for each question type). Repeat for each question of the same type within each section.

 

  a. Get True/False question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/trueFalseQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/trueFalseQuestions/{questionId}/choices

 

  b. Get Multiple-Choice question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/multipleChoiceQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/multipleChoiceQuestions/{questionId}/choices

 

  c. Get Many Multiple-Choice question and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/manyMultipleChoiceQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/manyMultipleChoiceQuestions/{questionId}/choices

 

  d. Get Matching question, array of premises, and array of choices.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}/premises

 

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/matchingQuestions/{questionId}/choices

 

  e. Get Short Answer question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/shortQuestions/{questionId}

 

  f. Get Essay question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/essayQuestions/{questionId}

 

  g. Get Fill-in-the-Blank question.

GET /users/{userId}/courses/{courseId}/exams/{examId}/sections/{sectionId}/fillintheblankQuestions/{questionId}

 

Optionally, the sequence can be GET each question and then submit its answer instead of GET all questions and then submit each answer as it is completed. Be sure to repeat for all questions in a section and all sections in an exam.
User submits answers.

7. Add answer for each question.

POST /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

 

  • {answerId}={questionId} being answered.
  • POST each answer ID only once. Repeating the POST to an existing answer will return an error.
User changes previously submitted answer. 8. Get answer (optional).

GET /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

 

9. Update answer.

PUT /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}/answers/{answerId}

If user manually completes exam...

10. Update attempt to completed status.

PUT /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}

  • Attempt instance is locked against any further changes.
  • Response body includes exam end time and links to user's exam instance and attempt instance.
  • Automatic processing occurs (for example, auto-grading if it had been enabled, notifications sent, etc.).
If exam duration is about to expire... 11. POST/PUT any saved answers before the exam duration expires (see steps 7 through 9).

 

12. Update attempt to completed status (see step 10).

  • Attempt instance is locked against any further changes once the Pearson_exam_token expires. The exam duration is calculated using the LearningStudio server time.
  • Any answers that are not POST/PUT to the attempt instance will be blocked once the Pearson_exam_token expires.
If exam duration expires... 13. Update attempt to completed status (see step 10).
  • Attempt instance is locked against any further changes.
  • Automatic processing occurs (for example, auto-grading if it had been enabled, notifications sent, etc.).
Optionally, display a summary of the grading results.

Review Exam Attempt

3132 reads
Always Learning
Pearson