Test Resource
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 |
| Read (Multiple Test Forms associated with Test Ref) |
GET | https://...surpass.com/api/v2/Test/{reference}/TestForms |
| Read (Multiple Test Forms associated with Test ID) |
GET | https://...surpass.com/api/v2/Test/{id}/TestForms |
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 Test resource.
Example GET request and response (JSON)
Example GET request and response (XML)
The GET Test method supports the ability to filter by test ID and reference. Calling the GET Test method provides the consumer with the ability to filter tests based on these attributes. You can send a separate request to retrieve all of the information about a test including the ID of the test in the request URL.
The GET Test method also allows users to retrieve information about any test forms associated with tests. Use the "scheduledTestFormsOnly":true parameter to search only for test forms that are currently scheduled.
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.