Pearson
Always Learning

API Group: 

You'll use this API to provision an exam instance for a user, which selects the user's specific questions from the question pool. Once provisioned, using a GET request here will return the details for the exam such as its title and description, as well as links to the attempt and section information.

Important: You must provision an exam instance before an attempt can be created (in which a student saves their answers). Be sure to read the Exams Data Model and Workflow Overview page.

Note: Creation of an exam attempt is allowed only between the exam's scheduled start and end date/times (if these dates have been set, which is not always true).

Note: Provisioning an exam for a student can only be done with OAuth 2 using that Student's access token.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 1.0a (for retrieving and deleting exam instances only)
OAuth 2.0 (required for provisioning)
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student, Administrator
Note that only a Student role can provision an Exam Instance.
Note that a Student role cannot delete an Exam Instance

API Request

API Endpoints

HTTP Verbs and URIs

POST /users/{userId}/courses/{courseId}/exams/{examId}{.format}
  • Provisions an exam instance for the specified user (typically a student).
  • Note that this endpoint can only be used with OAuth 2 and a user token for the user for whom you're provisioning the exam instance.
  • Only one exam instance can be created per user. Subsequent calls without deleting previous ones will throw an error message.
GET /users/{userId}/courses/{courseId}/exams{.format}
  • Retrieves the details for all provisioned exam instances for the user.
GET /users/{userId}/courses/{courseId}/exams/{examId}{.format}
  • Retrieves the details for a provisioned exam instance.
DELETE /users/{userId}/courses/{courseId}/exams/{examId}{.format}
  • Deletes an exam instance for the user (e.g., "resets" the exam).
  • Deleting an exam instance deletes all the user's answers and grades associated with submitted exams.

Parameters

Parameter Description Valid Values
{userId} LearningStudio User ID or relevant user overload.
  • Numeric ID issued by LearningStudio
  • loginid={clientString}|{username}
  • or replace /users/{userId} with /me
    (OAuth 2 only)
{courseId} LearningStudio Course ID or relevant course overload.
  • Numeric ID issued by LearningStudio
  • ccn={callNumber}
{examId} LearningStudio Exam ID. This is different from the Content Item ID, and can be retrieved from the Content Item Info APIs (in the links properties) or the Exam Details API. Numeric ID issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Query String Parameters

No Query String Parameters are supported.

Request Body

None of the request methods/verbs require a body. For POST, send an empty body.

API Response

HTTP Status Codes & Headers

This API returns the standard HTTP Status Codes used by the LearningStudio APIs. There are no special headers returned by the API.

If you attempt to provision an exam and get a 500 - Internal Service Error status code in response, it's quite probable the exam was created before June 1, 2012. The Exams API only works with exams that were created after that date. This includes exams that were originally created before that date and copied into a new course after that date.

Attempting to provision an exam that already exists will trigger a 400 - Bad Request status code. Attempting to provision an exam in OAuth 1 or with an OAuth 2 Access Token for a user that is not the specified user will trigger a 403 - Unauthorized status code.

When deleting an exam instance, the API will return a 204 - No Content status code on success.

Response Body

Format for DELETE

No body is returned.

Format for POST and GET

{
  "exam" : {
    "id" : {examId},
    "title" : "{title}",
    "description" : "{description}",
    "isRetakable": {isRetakableFlag},
    "duration": {duration} 
    "links" : [{
      "href" : "{sectionsHref}",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/section"
      },{
      "href" : "{attemptsHref}",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/attempt"
      }
    ]
  }
}

Note: If you retrieve all Exam Instances (.../exams{.format}, see Endpoints above), the parent property will be exams and its value will be an array of the objects described here.

Property Descriptions

Name Description
{examId} Exam Instance ID. It is the same as the exam ID from which it was created.
{examTitle} Exam title (if set). Note, this is not the title of the content item that contains the exam. The exam title is entered in the exam configuration screen.
{examDescription} Descriptive text to be display at the beginning of the exam (for example, exam instructions).
{isRetakableFlag} Indicates whether the user can retake the same exam after completing it (for example, a "practice" exam). To retake an exam, you'll create a new attempt. During an exam retake, the original set of exam questions/choices are presented. The user's original answers are discarded and replaced with the answers saved during the retake.

The values of this property will be boolean, either true or false.

{duration} Length of time in seconds before the exam ends and no further changes are allowed to the related attempts instance. Duration includes any adaptive adjustments made for the specified user (for example, the admin may have allocated additional exam time to a specified user because of mobility issues). The clock starts when you create an attempt.

If there is no time limit for this exam, the value will be zero ( 0 ).

{sectionsHref} Link to retrieve the Exam Sections (which contain questions) for this user.
{attemptsHref} Link to retrieve the Exam Attempts for this user and exam.

Example: Provision an Exam Instance

Request

Endpoint

POST /users/88888/courses/4321/exams/999999

Response

Body

{
  "exam" : {
    "id" : 999999,
    "title" : "Practice Exam",
    "description" : "This exam matches the format of an exam that will be taken at the end of the course.",
    "isRetakable": true,
    "duration": 0, 
    "links" : [{
      "href" : "https://api.learningstudio.com/users/88888/courses/4321/exams/999999/sections",
      "rel" : "https://api.learningstudio.com/rels/user/course/exam/section"
      }
    ]
  }
}
3744 reads
Always Learning
Pearson