Pearson
Always Learning

API Group: 

This API starts the exam for the user. It creates an "attempt" which is analogous to an answer booklet where students enter their answers, and is separate from the main Exams records.

Prior to starting an attempt, you must provision an exam instance for a user, and optionally you can retrieve the exam structure and question list for each section (not including the question text). You must start an attempt to gain access to question text and answer options.

Exam Duration

Some exams are timed. The timer starts when the attempt is created and this API will provide the timestamp of when it started ticking. To know how long the user has, see the duration property provided in the provisioned exam instance.

Important: If an exam is timed, the student's answers must be submitted to the attempt before it expires. You can still mark the attempt as complete (see PUT) after the time expires, but no additional answers can be submitted after that time.

Exam Security

This API returns a "Pearson Exam Token" which must be sent with API calls related to retrieving question and answer option text, and submitting answers. You should cache the exam token in your application. If for any reason you need to retrieve the exam token, you can use a GET on this API. The exam token is valid as long as the attempt is valid, that is, until the timer runs out for timed exams, or forever for untimed exams. See Exam Security.

Retaking Exams

Note that if an exam is retakable (see the isretakable property provided in the provisioned exam instance), you can start a new attempt by repeating this API. However the previous attempt should be marked as complete (see PUT) before creating a new attempt. Only one attempt can exist at a time, and only the most recent attempt is saved.



Supported Roles and Authentication Protocols

Type Supported Values
Authentication Protocols OAuth 2.0
Valid for Roles (OAuth 2): Professor, Teaching Assistant, Student

Note: Only the user for whom the exam instance was provisioned may start, edit, and complete an attempt. So while technically teachers and teaching assistants can take an exam, in practical terms this API is only used by Student roles with OAuth 2 Access Tokens.

API Request

API Endpoints

HTTP Verbs and URIs

POST /users/{userId}/courses/{courseId}/exams/{examId}/attempts{.format}
  • Starts an exam attempt.
PUT /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}{.format}
  • Used to mark an attempt as complete.
GET /users/{userId}/courses/{courseId}/exams/{examId}/attempts/{attemptId}{.format}
GET /users/{userId}/courses/{courseId}/exams/{examId}/attempts{.format}
  • Retrieves the details of an attempt, useful for getting the exam token or starting timestamp.
  • Note: Because only one attempt can exist at a time, these two API calls are essentially the same results with minor differences in payload formatting (the latter is formatted as an array with a single object).

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
{attemptId} LearningStudio Exam Attempt ID. Numeric ID issued by LearningStudio
{.format} Desired format of response data. See Response Formats. .json , .xml , or Blank

Request HTTP Headers

In addition to the standard Authentication headers, you may need headers that regulate Exam Security. See Exam Security.

Format

Pearson-Exam-Password: {examPassword}
Pearson-Exam-Token: {examToken}

Parameter Descriptions

Name Description Valid Values Required
{examPassword} A password provided by the teacher. This is not retrievable by API. Exam Security Plain text string Only if set by teacher, for all verbs
{examToken} The Pearson Exam Token provided by a POST or GET to this API Plain text string Always for PUT

Query String Parameters

No Query String Parameters are supported.

Request Body

For POST and GET Requests

None

For PUT Requests

{
  "attempt" : {
    "isCompleted": {isCompletedFlag}
  }
}

Property Descriptions

Property Description Valid Values
{isCompletedFlag} Indicates whether the attempt is complete and the answers should be submitted for the student. This is analogous to a student turning in an answer sheet in a classroom exam.

Important: Once an attempt is marked as complete, it cannot be changed back to open.

  • true - exam is complete

API Response

Response Header

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

Response Body

Format

This payload is used for all verbs, with minor variations as described in the table below.

{
  "attempt": {
  	"id": {attemptId},
  	"pearsonExamToken": {examToken},
  	"startUtc": {startTimestamp},
  	"endUtc": {endTimestamp},
  	"isCompleted": {isCompletedFlag},
  	"links": [{
	  	"href": {examInstanceHref},
	  	"rel": "https://api.learningstudio.com/rels/user/course/exam"
	  },{
	  	"href": {attemptAnswersHref},
	  	"rel": "https://api.learningstudio.com/rels/user/course/exam/attempt/answer"
	  },{
	  	"href": {attemptSummaryHref},
	  	"rel": "https://api.learningstudio.com/rels/user/course/exam/attempt/summary"
	  }]
  }
}

Property Descriptions

Name Description
{attemptId} Attempts ID.
{examToken} Unique exam token for attempts instance. Use this as the header for the Pearson-Exam-Token HTTP header where required.
{startUtc} The timestamp of when the attempt was created and exam was started. This is the time that the timer started if the event is timed. Format is ISO-8601, e.g. YYYY-MM-DDTHH:MM:SSZ.
{endUtc} The timestamp of when the attempt was marked as complete. Format is ISO-8601, e.g. YYYY-MM-DDTHH:MM:SSZ.
Note: This property is only included when it has a value, namely when the attempt has been marked as complete.
{isCompletedFlag} Indicates whether the exam is completed and if changes are allowed to the attempts instance. Format is boolean (e.g., true or false).
{examInstanceHref} A URL to retrieve the details of the provisioned exam instance.
{attemptAnswersHref} The URL to which you'll send a user's question answers (or retrieve previously saved answers). See Answer Exam Questions
{attemptSummaryHref} The URL to retrieve the student's exam summary (the number of points earned, for questions that can be automatically graded). Note, this URL is provided but not functional until the attempt is marked as complete. See Review Exam Summary (Results).

Example: Start a New Attempt

Request

Endpoint

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

Response

Body

{
  "attempt" : {
    "id" : 2323,
    "startUtc" : "2011-08-23T21:52:11Z", 
    "isCompleted": false,
    "pearsonExamToken" : "ex8ryIaysvDnL3erNYkHGWzCN63nOnGGe38VwYtWxReMuxGyfM6gLAkfBCREDODg="
    "links" : [{
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam"
    }, {
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999/attempts/2323/answers",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/attempt/answers"
    }, {
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999/attempts/2323/summary",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/attempt/summary"
    }]
  }
}

Example: Mark an Attempt as Complete

Request

Endpoint

 
PUT /users/88888/courses/4321/exams/999999/attempts/2323

HTTP Headers

 
Pearson-Exam-Token: ex8ryIaysvDnL3erNYkHGWzCN63nOnGGe38VwYtWxReMuxGyfM6gLAkfBCREDODg

Body

{
  "attempt" : {
    "isCompleted" : True
  }
}

Response

Body

{
  "attempt" : {
    "id" : 2323,
    "startUtc" : "2011-08-23T21:52:11Z", 
    "endUtc" : "2011-08-23T22:20:38Z", 
    "isCompleted": true,
    "pearsonExamToken" : "ex8ryIaysvDnL3erNYkHGWzCN63nOnGGe38VwYtWxReMuxGyfM6gLAkfBCREDODg="
    "links" : [{
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam"
    }, {
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999/attempts/2323/answers",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/attempt/answers"
    }, {
      "href" : "http://api.learningstudio.com/users/88888/courses/4321/exams/999999/attempts/2323/summary",
      "rel" : "http://api.learningstudio.com/rels/user/course/exam/attempt/summary"
    }]
  }
}
4323 reads
Always Learning
Pearson