TestSession Resource

The Test Session resource refers to the specific session where a candidate takes a test this is inclusive of its journey from invigilate to marking and moderation, once it is released/voided it becomes a result entity in the Surpass API. The current main use of this resource is to update a test sessions state. This may be necessary if the invigilator/consumer wishes to pause, resume or void a test via an external system. The test can be identified by its ID or by its unique keycode in Surpass.

The Surpass API will only allow a test session to move to a valid Surpass state. For example a test cannot be moved to "Paused" if it is in a "Ready" state because the test hasn't started yet.

State Transitions

Tests can be voided at all states in the invigilation screen, however if they have been setup to be computer marked with no moderation you will not be able to void a finished test as this will be warehoused and become a result immediately. If the test session is finished/submitted but available in marking or moderation the Surpass API will allow an external system to update the test session to voided. Other state transitions include:

InProgress > Paused
Paused > InProgress


TestSession Resource

Below we have listed the operations, HTTP verbs and an example URL for the TestSession resource within the Surpass API.
Operation HTTP Verb Example URL
Search and Filter GET https://...surpass.com/api/v2/TestSession/
Read GET {id} https://...surpass.com/api/v2/TestSession/1
Read GET {keycode} https://...surpass.com/api/v2/TestSession/H76RBD8P
Update {id} PUT https://...surpass.com/api/v2/TestSession/1
Update {keycode} PUT https://...surpass.com/api/v2/TestSession/H76RBD8P
Create {keycode}/ItemMarks POST https://...surpass.com/api/v2/TestSession/H76RBD8P
Create {keycode}/ItemResponses POST https://...surpass.com/api/v2/TestSession/H76RBD8P

Attributes for the TestSession Resource (PUT)

Within the table below we have provided all of the attributes included in the TestSession resource. This includes the attribute name, data type and if the attribute is mandatory when sending a PUT request. Remember that if an attribute is not mandatory, it can be omitted from the body of the PUT request.
Attribute Name Type Description Unique Identifier
id Int The unique test session ID X
Keycode String This is the unique keycode generated in Surpass. It appears in the invigilate screen to identify the test session. X
testState Enum This refers to the test sessions state. Available states enumerations: 'InProgress', 'Paused', and 'Voided'.
voidReason Enum The reason why a test is being voided. One of the following enumerations is required: 'Absent', 'Withdrawn', 'Other', 'PartiallyCompleted'.
voidMessage String Additional details if the void reason 'Other' is selected.
forceLocalVoid Boolean Voiding a test that is scheduled for SurpassLocal delivery will target it to be voided the next time it communicates with Surpass but this can be forced by sending this property.
offlineDelivery boolean Allows tests that have been 'Downloaded to Local' but not yet started by the candidate to be reverted 'Scheduled but Locked' state on the Central server. Once changed the Test will not be run from SurpassLocal.

Attributes for the TestSession Resource (GET)

The table below contains all the attributes returned by the GET request. It will also include the id, keycode and testState as stated above. The list of possible testStates that may be brought back can be found here.
Attribute Name Type Description Unique Identifier
href string The link used to retrieve the TestSession information. X
keycode string The keycode generated for the candidate to enter the test. X
testState Enum This refers to the test sessions state. Available states enumerations: 'InProgress', 'Paused', and 'Voided'.
test / id int The unique ID of the test that has been scheduled. X
test / reference string The test reference.
test / name string The test name.
centre / id int The id of the centre the test was scheduled at. X
centre / reference string The reference given to the centre.
centre / href string The URL to retrieve information on the centre.
candidate / id int The id of the candidate scheduled for the test. X
candidate / reference string The candidate reference.
candidate / href string The URL to retrieve information on the candidate.
startDate date The date for the exam window to begin. DD/MM/YYYY
endDate date The date for the exam window to end. DD/MM/YYYY
startTime time The start time of the window in which the exam can be taken within the date range specified above. TTTT
endTime time The end time of the window in which the exam can be taken within the date range specified above. TTTT
testForm / id int The id of the Test Form the candidate has taken. X
testForm / reference string The Test Form Reference.
testForm / name string The Test Form name.
duration int The length of the test, in minutes.
requiresInvigilation boolean States whether the test requires a PIN or an Invigilator.
qualityReview boolean States whether the test has the HTML-Only Quality Review panel enabled.

Attributes for the TestSession Resource (POST - ItemResponses)

For tests that have been scheduled where 'uploadResponses' has been marked as 'true' on the TestSchedule and in the UI, users will be able to upload Item Responses for MCQ, MRQ and Either/Or questions. This is intended for tests that have been completed on paper and then scanned using OMR software.
Attribute Name Type Description
questionNumber string The number of the question
answer string The responses that the candidate gave in response to the question. For MRQs, the responses should be pipe separated.

Attributes for the TestSession Resource (POST - ItemMarks)

For tests that have been scheduled where 'uploadResponses' has been marked as 'true' on the TestSchedule and in the UI, users will be able to upload Item Marks for all questions. This is intended for tests that have been completed on paper and then scanned using OMR software.
Attribute Name Type Description
questionNumber string The number of the question
mark num The marks that the candidate achieved for the particular question.
Completion Date
Users are able to add completionDate as a parameter to these POST requests. This is in cases where the OMR upload has faulted and in cases where tests have not been sat on the date that the result is being imported. This field is optional.

PUT Request and Return

PUT Requests should reference the ID or Reference within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.

Example PUT request & response (JSON)
Example PUT request & response (XML)

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.


GET Request and Return

GET Requests should reference the ID or Keycode of the particular TestSession and can be called by using the URL. Any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page "Understanding the Surpass API".

Example GET request & response (XML)


Required Permissions

To successfully call the PUT TestSession method the user specified in the header of the request must have the 'Invigilate: Void Test' permission in Surpass and be associated to the relevant centre and subject that is contained within the request.

Feedback and Knowledge Base