Test Resource

The Surpass API can be used to import and export tests from Surpass. All test level settings are able to be migrated and retrieved. In Surpass the entity 'Test' are child resource of Subjects and a parent resource of Test Forms (versions of tests).

Test Resource

Below we have listed the operations, HTTP verbs and an example URL for the Test Resource within the Surpass API.
Operation HTTP Verb Example URL
Create POST https://...surpass.com/api/v2/Test
Read (Filter) GET https://...surpass.com/api/v2/Test?$filter=name eq 'Test'
Read (Individual) GET https://...surpass.com/api/v2/Test/1
Attributes for the Test Resource

Within the table below we have provided all of the attributes included in the test 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 Type Notes Unique Identifier Mandatory for Create (POST)
subject Resource ID or Reference can be supplied. X
name string The name of the test X
reference string The test reference X
status string Can be "Draft", "Live" or "Retired".
certifiedAccessible boolean Indicates if test is compatible with the JAWS screenreader or not. Should only be true if all test form content is compatible with JAWS.
useAsTemplate boolean When "true", the test can be cloned as a new test.
examType string Can either be "ComputerBasedTest" or "ComputerBasedProject"
allowTimeExtensionWhileInProgress boolean If set to "true" users to extend the duration of an in-progress test for up to 24 hours more than the original end time.
attemptAutoSubmit boolean When a candidate’s test has not been submitted within a certain time period, this setting will automatically void the test (if "false") or submit the test with the existing responses it contains (if "true").
resultsUploadGracePeriod int The number of days that Test Administration will wait before either auto-submitting or voiding tests
requiresSecureClient boolean
secureClientMode string Can either be "Unlocked" or "Locked"
requiresInvigilation boolean If set to true, a candidate will have to input a PIN before they can sit their test.
certifiedForTabletDelivery boolean
numberOfResits int When omitted, there is no restriction put on the number of resits.
validFromDate Date/Time
expiryDate Date/Time
testWindowStartTime string
testWindowEndTime string
randomiseTestForms boolean
allowTestFormRecycling boolean
deliveryOptions string Can be: "DeliverSameExamToAllCandidates" or "DeliverDifferentExamsTo
testDistribution string Can be: "Online", "Offline" or "Both".
markingType String Can be: "StandardMarking", "Psychometric" or "PaperMarking".
candidateDetails / required boolean
candidateDetails / duration int Provide duration as a value in minutes.
NDA / required boolean
NDA / duration int Provide duration as a value in minutes.
NDA / confirmationText string
progessBar / required boolean
progressBar / mode string Can be set as "ItemBased" or "MarksBased".
testStyle string Can be "StandardNavigation", "ForwardOnlyNavigation", "CustomBranding", "CustomBrandingForwardOnly".
styleProfile / testProfile int Can provide the ID or Reference
displayReport boolean
displayReportPrintButton boolean Can only be enabled when displayReport is "True".
defaultNavigationLanguage string For a full list of supported delivery languages, please consult this article.
allowLanguageOverride boolean
showPageRequiresScrollingAlert boolean
easyPvalue int Between 0 and 1. Lower easy value.
maxEasyPvalue int Between 0 and 1. Upper easy value.
hardPvalue int Between 0 and 1. Upper hard value.
minHardPvalue int Between 0 and 1. Lower hard value.
mininumResitTime int Determines the amount of time which must elapse before a resit can be attempted. Enter value in days.
generateTestStatistics boolean
allowPackagingOfCandidateResponses boolean
automaticallyShowToCentre boolean
autoCreatePIN boolean If set to "false", the Test Scheduler will set the PIN when the test is scheduled.
strictControlReasonableAdjustments boolean
enableCandidateLogging boolean
scoreBoundaries / type string Can be set as "Percentage" or "Result". Defines how score is displayed in Candidate Breakdown Report.
boundaries / modifier string Less than ("lt") or greater than ("gt").
boundaries / value int Percentage for the score boundary.
boundaries / description string Configurable text shown to the candidate indicating how they performed against the learning outcome. I.e. "Not Met", "Met", "Exceeded."
boundaries / higherBoundary boolean Set the boundary for High Marking Items as opposed to Low Marking Items.
boundaries / higherBoundary boolean Set the boundary for High Marking Items as opposed to Low Marking Items.
userAssociations / restrictUserAccess boolean Strictly enforces the allocations of markers and moderators to the test during scheduling.
userAssociations / enableMarker boolean Allows individual markers to be assigned during scheduling.
userAssociations / requireMarker boolean Markers must be assigned to a test at the point of scheduling.
userAssociations / enableModerator boolean Allows individual moderators to be assigned during scheduling.
userAssociations / requireModerator boolean Moderators must be assigned to a test at the point of scheduling.

Additional Notes

In the UI, “restrictNumberOfResits” can only be added if enable is selected. If this is not specified it will be assumed it is not enabled.


POST Request and Return

The POST Test method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

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.

Example POST request and response (JSON)
Example POST request and response (XML)


GET Request and Return

The GET Test 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 Item resource.

Example GET request and response (JSON)
Example GET request and response (XML)

The GET Test method supports the ability to filter by the subject {id, reference}, test reference and status. Calling the GET Test method provides the consumer with the ability to filter tests based on these attributes, a separate request should be sent to retrieve all of the information about a test including the ID of the test in the request URL.


Required Permissions

To successfully call the Test Resource, the user specified in the header of the request must have the 'Create Tests' role in Surpass.


Feedback and Knowledge Base