SurpassLocal - TestSession Resource

When a test has been scheduled and has become locked, the SurpassLocal API can be used to update the test session state. This may be necessary if the invigilator wishes to pause, resume, unlock or void a test via an external system. The test can be identified by its ID or by its unique keycode in Surpass.

TestSession Resource

Below we have listed the operations, http verbs and an example URL for the TestSession resource within the SurpassLocal API.



Example URL



Read (individual by ID)


Read (individual by keycode)


Update by id


Update by keycode


Attributes for the TestSession Resource

Within the table below we have provided all of the attributes included in the test session resource. This includes the attribute name, data type and if the attribute is mandatory when sending a POST request. Remember that if an attribute is not mandatory, it can be omitted from the body of the POST request. 

Attribute Name



Unique Identifier



Unable to PUT




This is the unique keycode generated in Surpass.




Unable to PUT




It is only possible to change state:
InProgress > Paused

Paused > InProgress

Ready, LockedByPin, LockedForInvigilator, Paused, InProgress > Voided




Possible values:
Absent, Withdrawn, PartiallyCompleted, Other.
Not required - Auto will be used when not specified.




Required when voidReason is Other.




Additional information about the candidate,


GET Request and Return

The GET TestSession resource can be called directly by browsing to 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 for the TestSession resource. 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 (JSON)

Example GET request & response (XML)

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 SurpassLocal API can be found here.

Filtering results on Resource objects

The GET TestSession method allows you to filter on resource objects contained within the TestSession Resource. 

You can filter on the date the test session was last modified, for example through a state change or interaction:$filter=modifiedDate ge 2019-04-29T10:20:00Z

Or you can filter by the date range of the test session: TestSession?$filter=enddate ge 2019-04-22T00:00:00Z and startdate le 2019-04-27T00:00:00Z

Required Permissions

To successfully call the methods in the Surpass Local TestSession Resource, the user validating the requests must exist within BTL’s CMS system. If you require a password reminder or a new account to be created, send a request to the BTL Service Desk (


Feedback and Knowledge Base