Test API

A test (also known as an “examination” or “assessment”) is a systematic procedure designed to measure candidates’ skills and/or knowledge about a particular topic. In Surpass, a “test” contains the high-level settings (such as whether the test is to be taken in SecureClient or a web browser) and a “test form” contains the question content.

The Test API resource is used to list tests and their associated test forms, retrieve tests, and create tests.

This article explains what calls can be made to the Surpass API using the Test resource.

Import this API into your Postman Workspace

Listing tests

get /api/v2/Test

Send a request to the endpoint to retrieve a list of tests. Refer to the available parameters to influence the response. No request body is required.

Parameters

Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.

EXAMPLE: The endpoint /api/v2/Test?$filter=reference eq Geography would return the test with the reference ‘Geography’.

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
top	query OPTIONAL	`/api/v2/Test?$top={top}`	Defines number of responses to return when paging a response, where `{top}` is a number between 1 and 40.
skip	query OPTIONAL	`/api/v2/Test?$skip={skip}`	Defines how many responses to skip when paging a response, where `{skip}` is a number that should not exceed the total number of responses.
filter	query OPTIONAL	`/api/v2/Test?$filter={filter} {operator} {value}`	Filters results, searching for an exact match. For an exact match: `{filter}` is `reference`, `subject/id`, `subject/reference`,`{operator}` is `eq` (equal to), and `{value}` is the string or integer the filter query looks for an exact match for in the request.

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top, skip, and other parameters are joined using &. For example, the endpoint /api/v2/Test?$top=10&$skip=25 would skip the first 25 results and return 10.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
    "count": 831,
    "top": 10,
    "skip": 0,
    "pageCount": 84,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/Test?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "reference": "Test1",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/1"
        },
        {
            "id": 2,
            "reference": "Test2",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/2"
        },
        {
            "id": 3,
            "reference": "Test3",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/3"
        },
        {
            "id": 4,
            "reference": "Test4",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/4"
        },
        {
            "id": 5,
            "reference": "Test5",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/5"
        },
        {
            "id": 6,
            "reference": "Test6",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/6"
        },
        {
            "id": 7,
            "reference": "Test7",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/7"
        },
        {
            "id": 8,
            "reference": "Test8",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/8"
        },
        {
            "id": 9,
            "reference": "Test9",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/9"
        },
        {
            "id": 10,
            "reference": "Test10",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/10"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Retrieving test information

get /api/v2/Test/{id}

Send a request to the endpoint to retrieve information for a specific tests using its ID. No request body is required.

Parameters

Name

Parameter

Input

Description

authorization

header

MANDATORY

Basic {credentials}

Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string.

accept

header

OPTIONAL

application/json or application/xml

Determines data format of the response, which can be either JSON or XML.

path

OPTIONAL

/api/v2/Test/{id}

Returns information for the specified test, where {id} is the test’s unique identifier.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
    "count": null,
    "top": null,
    "skip": null,
    "pageCount": null,
    "nextPageLink": null,
    "prevPageLink": null,
    "response": [
        {
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
                "name": "Geography Subject 1"
            },
            "name": "Final Year Geography Test",
            "reference": "Test1",
            "status": "Live",
            "certifiedAccessible": false,
            "useAsTemplate": false,
            "ExamType": "ComputerBasedTest",
            "allowTimeExtensionWhileInProgress": false,
            "attemptAutoSubmit": true,
            "resultsUploadGracePeriod": 14,
            "requiresSecureClient": true,
            "requiresBYODMode": null,
            "secureClientMode": "Locked",
            "requiresInvigilation": true,
            "certifiedForTabletDelivery": false,
            "numberOfResits": null,
            "validFromDate": "2020-10-22T00:00:00",
            "expiryDate": "2030-10-23T00:00:00",
            "testWindowStartTime": "00:00",
            "testWindowEndTime": "23:59",
            "randomiseTestForms": true,
            "allowTestFormRecycling": true,
            "deliveryOptions": "DeliverDifferentExamsToAllCandidates",
            "testDistribution": "Online",
            "markingType": "StandardMarking",
            "candidateDetails": {
                "required": true,
                "duration": null
            },
            "NDA": {
                "required": true,
                "duration": null,
                "confirmationText": "By ticking this box you confirm your details are correct and you accept the awarding organisation's code of conduct."
            },
            "progressBar": {
                "required": true,
                "mode": "MarksBased"
            },
            "testStyle": "CustomBranding",
            "styleProfile": {
                "testProfile": {
                    "id": null
                },
                "displayReport": false,
                "displayReportPrintButton": false
            },
            "defaultNavigationLanguage": "English",
            "allowLanguageOverride": true,
            "showPageRequiresScrollingAlert": false,
            "easyPvalue": 0.700,
            "maxEasyPvalue": 0.900,
            "hardPvalue": 0.300,
            "minHardPvalue": 0.100,
            "minimumResitTime": 0,
            "generateTestStatistics": true,
            "allowPackagingOfCandidateResponses": true,
            "automaticallyShowToCentre": false,
            "autoCreatePIN": true,
            "strictControlReasonableAdjustments": false,
            "enableCandidateLogging": false,
            "scoreBoundaries": {
                "type": "Percentage",
                "boundaries": [
                    {
                        "modifer": "lt",
                        "value": 40,
                        "description": "Not met",
                        "higherBoundary": true
                    },
                    {
                        "modifer": "lt",
                        "value": 40,
                        "description": "Not met",
                        "higherBoundary": false
                    },
                    {
                        "modifer": "gt",
                        "value": 40,
                        "description": "Close to met",
                        "higherBoundary": true
                    },
                    {
                        "modifer": "gt",
                        "value": 40,
                        "description": "Met",
                        "higherBoundary": false
                    },
                    {
                        "modifer": "gt",
                        "value": 45,
                        "description": "Met",
                        "higherBoundary": true
                    },
                    {
                        "modifer": "gt",
                        "value": 80,
                        "description": "Exceeded",
                        "higherBoundary": true
                    }
                ]
            },
            "userAssociations": {
                "restrictUserAccess": false,
                "enableMarker": false,
                "requireMarker": false,
                "enableModerator": false,
                "requireModerator": false
            },
            "isHtmlCompatible": true
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Response schema

The response schema contains a description of every property that can be returned for this endpoint.

count integer

Details how many tests there are in total. This is null because the information retrieved is for a specific test.

top integer

Details number of tests returned in the response. This is null because the information retrieved is for a specific test.

skip integer

Details how many tests were skipped to display those in the response. This is null because the information retrieved is for a specific test.

pageCount integer

Details how many pages of tests there are. This is null because the information retrieved is for a specific test.

nextPageLink string

The endpoint to call the next page of tests. This is null because the information retrieved is for a specific test.

prevPageLink string

The endpoint to call the previous page of tests. This is null because the information retrieved is for a specific test.

response array

Contains the rest of the response.

subject object

Contains the subject that the test is in.

subject/id integer

The subject’s unique identifier.

subject/reference string

The subject’s unique reference code.

subject/href string

The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.

subject/name string

The subject’s name.

name string

The test’s name.

reference string

The test’s unique reference code.

status enumeration

The test’s workflow status. The available workflow statuses are Draft, Live, and Retired. Every test starts at Draft and must be set to Live before any of its test forms can be scheduled.

certifiedAccessible Boolean

Determines whether the JAWS screen reader is enabled for legacy tests.

useAsTemplate Boolean

Determines whether the test can be used as a template for cloning. For more information, read Cloning tests.

ExamType enumeration

Determines the type of test. The available options are:

ComputerBasedTest – A single-sitting assessment measured in minutes or hours.
ComputerBasedProject – A long-term assessment measured in days or weeks. Candidates can log into their test at any time between the start and end dates. Computer based projects must be taken in web delivery. For more information, read Creating a computer based project.

allowTimeExtensionWhileinProgress Boolean

Determines whether the Allow Time Extension While In Progress setting is enabled. If true, allows invigilators to add up to 24 hours to the duration of In Progress tests.

attemptAutoSubmit Boolean

Determines whether the Attempt Auto Submit setting is enabled. If true, allows candidates taking tests in SecureClient to upload their responses at a later date if their internet connection is lost during the test. Candidates must re-open SecureClient with an active internet connection to automatically submit their responses.

If false is cleared, Surpass automatically voids tests not submitted in time.

resultsUploadGracePeriod integer

Sets the amount of days that Surpass waits before automatically voiding tests that have not been submitted.

NOTE: attemptAutoSubmit must also be set to true.

requiresSecureClient Boolean

Determines whether the Requires SecureClient setting is enabled. If true, the test cannot be delivered in a web browser.

requiresBYODMode Boolean

Determines whether the Requires BYOD Mode setting is enabled. If true, candidates must sit the test in BYOD SecureClient. For more information, speak to your Surpass Account Manager.

IMPORTANT: The requiresSecureClient property must be true, and secureClientMode set to Locked. enableCandidateLogging must also be true.

secureClientMode enumeration

Sets the SecureClient delivery mode:

Unlocked – Allows candidates to minimise SecureClient and browse their device and/or the internet freely.
Locked – Prevents candidates leaving SecureClient during the test.

requiresInvigilation Boolean

Determines whether the Requires Invigilation setting is enabled. If true, creates a second security wall after the keycode screen to prevent candidates from gaining early entry to tests. Tests can either be locked by a PIN or require manual unlocking by invigilators. For more information, read About invigilation.

certifiedForTabletDelivery Boolean

Determines whether the Certified for Tablet Delivery setting is enabled. If true, the test will be delivered in the SurpassDelivery tablet app.

numberOfResits integer

Sets the amount of times candidates can resit a test. If a number is provided, the Limit Resits setting is enabled in the UI. Read ‘Test Interface Options’ in About test settings for more information. If null, Limit Resits is disabled.

If set to 0, candidates cannot resit a test after their first attempt.

validFromDate string

Sets the Valid From date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format.

expiryDate string

Sets the Expiry date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format. Defaults to 10 years.

testWindowStartTime string

Sets the Start Time for the period of time in which candidates can enter the test on any given day, in HH:MM format.

testWindowEndTime string

Sets the End Time for the period of time in which candidates can enter the test on any given day, in HH:MM format.

randomiseTestForms Boolean

Determines whether the Randomise Test Forms setting is enabled. If true, distributes test forms in a random order to candidates if there is more than one form of the same test.

allowTestFormRecycling Boolean

Determines whether the Allow Test Form Recycling setting is enabled. If true, enables candidates to take the same test form if they resit a test. If false, candidates are unable to resit a test if they have already sat all available test forms.

deliveryOptions enumeration

Determines the test delivery options available to Test Administration users. The available options are:

DeliverSameExamToAllCandidates – If a test has multiple test forms, candidates receive the same test form. If the test form has dynamic sections, the rules are run once to create a static test form that is delivered to all candidates.
DeliverDifferentExamsToAllCandidates – If a test has multiple test forms, candidates receive different test forms. If a given test form has dynamic sections, the rules are run as many times as necessary to create a unique test form for each candidate.
Either– Allows Test Administration users to decide whether to deliver the same test or different tests at the point of scheduling.

testDistribution enumeration

Always returns Online: tests can only be delivered online and must be scheduled in Surpass.

NOTE: This is a retired property and has no bearing on tests.

markingType enumeration

Determines how the test will be marked in Test Administration. The available options are:

StandardMarking – Makes the test available for marking in either the Surpass Mark screen or SecureMarker.
Psychometric – Enables psychometric references for ContentProducer items.
PaperMarking – Makes the test available for marking in the Surpass Paper Mark screen.

candidateDetails object

Contains the Requires User Details confirmation settings’ information.

candidateDetails/required Boolean

Determines whether the Requires User Details confirmation setting is enabled. If true, forces candidates to confirm their personal details before starting the test.

candidateDetails/duration integer

The time limit for candidates to confirm their details, in minutes. The accepted value range is 0–60. A value of 0 (or null) gives candidates unlimited time to confirm their details.

NDA object

Contains the Candidate Agreement settings’ information.

NDA/required Boolean

Determines whether the Candidate Agreement setting is enabled. If true, forces candidates to agree to terms before starting the test.

NDA/duration integer

The time limit for candidates to agree to the terms, in minutes. The accepted value range is 0–60. A value of 0 (or null) gives candidates unlimited time agree to the terms.

NDA/confirmationText string

The candidate agreement terms in text format.

progressBar object

Contains the progress bar settings’ information.

progressBar/required Boolean

Determines whether the Show Test Progress setting is enabled. If true, displays the progress bar to candidates. The progress bar shows candidates where they are in the test.

progressBar/mode enumeration

Determines the progress bar’s mode. The available options are:

ItemBased – Displays candidate progress based on how many items they have attempted versus the total number of items in the test. For example, if there are 10 items in a test and a candidate has attempted six, their progress is displayed as 60%.
MarksBased – Displays candidate progress based on how many marks are in the items they have answered versus the total number of marks in the test. For example, if a test has five Multiple Choice questions worth one mark each and an Essay question worth ten marks, the progress bar will go up 6.66% with each Multiple Choice question answered.
2 (Item based fraction text) – Displays candidate progress as a fraction, with the number of attempted questions over the total number of questions in the test. For example, if there are twelve questions in a test and a candidate has answered three, the candidate will see ‘3/12 Items Attempted’.

testStyle enumeration

Determine the test’s navigation style. The available options are:

CustomBranding – Candidates can move freely through the test.
CustomBrandingForwardOnly – Candidates can only move to the next item.

styleProfile object

Contains the test profile’s information. For more information on test profiles, read About the Test Profiles screen.

styleProfile/testProfile object

Contains the test profile’s information.

styleProfile/testProfile/id integer

The test profile’s unique identifier.

styleProfile/displayReport Boolean

Determines whether the Display Report setting is enabled. If true, allows candidates to view a score report after a test.

styleProfile/displayReportPrintButton Boolean

Determines whether the Display Report Print Button setting is enabled. If true, allows the score report to be printed.

defaultNavigationLanguage enumeration

Determines the language used for the test driver’s interface and menus. This does not affect item content. For a list of all available languages, read About Surpass test languages.

allowLanguageOverride Boolean

Determines whether the Change Language When Scheduling setting is enabled. If true, allows Test Administration users to change the Test Driver Language setting at the point of scheduling.

showPageRequiresScrollingAlert Boolean

Determines whether the Show ‘Page Requires Scrolling’ Alert setting is enabled. If true, displays an alert to candidates in legacy tests when item content is larger than the window and requires a scroll.

NOTE: Standard tests have a built-in scrolling alert that is enabled by default.

easyPvalue integer

The minimum Easy P value. For more information on P values, read ‘P Value Ranges’ in About test settings.

maxEasyPvalue integer

The maximum Easy P value. For more information on P values, read ‘P Value Ranges’ in About test settings.

hardPvalue integer

The maximum Hard P value. For more information on P values, read ‘P Value Ranges’ in About test settings.

minHardPvalue integer

The minimum Hard P value. For more information on P values, read ‘P Value Ranges’ in About test settings.

generateTestStatistics Boolean

NOTE: This is a retired property and has no bearing on tests..

allowPackagingOfCandidateResponses Boolean

Determines whether the Allow Packaging of Candidate Responses setting is enabled. If true, enables candidates’ scripts to be downloaded as a ZIP file in the Moderate, Results, and Audit screens.

automaticallyShowToCentre Boolean

Determines whether the Automatically Show To Centre setting is enabled.

NOTE: This is a retired property and has no bearing on tests.

autoCreatePIN Boolean

Determines whether the Auto Create PIN setting is enabled. If true, a six character PIN is generated for the test. Candidates can use this PIN to unlock their tests if requiresInvigilation is true.

If Requires Invigilation is enabled and this property is false, invigilators must manually unlock candidates’ tests.

strictControlReasonableAdjustments Boolean

Determines whether the Enable strict control for Reasonable Adjustments setting is enabled. If true, allows users in the Schedule and Invigilate screens to only award extra time to candidates with reasonable adjustments.

NOTE: This only affects users with the Add extra time to tests with strict control for reasonable adjustments permission.

enableCandidateLogging Boolean

Determines whether the Enable Candidate Logging setting is enabled. If true, enables a secure log of candidates’ interactions in the test. This log can only be viewed in the database.

WARNING: Candidate logs can take up space in the database and this may result in charges for extra storage.

scoreBoundaries object

Contains the candidate score boundaries information. If your test items have been set up with Learning Outcomes, you can define the score boundaries you want the candidate to meet for each Learning Outcome.

scoreBoundaries/type enumeration

Determines whether the score boundaries are Percentage or Results-based.

scoreBoundaries/boundaries array

Contains each score boundary’s information.

NOTE: A separate object is returned for each score boundary.

scoreBoundaries/boundaries/modifier enumeration

Determines the score boundary’s modifier. This can be either less than (lt) or greater than (gt).

scoreBoundaries/boundaries/value integer

The score boundary’s value (percentage).

scoreBoundaries/boundaries/description string

The score boundary’s name. For example, ‘Not met’.

scoreBoundaries/boundaries/higherBoundary Boolean

Determines whether score boundary is a high marking item boundary.

There are two sets of boundaries. High Marking Item Boundaries are used for Learning Outcomes that have more than ten marks in the test and have four boundaries by default. Low Marking Item Boundaries are used for Learning Outcomes that have less than ten marks in the test and have two boundaries by default.

TIP: Low Marking Item Boundaries should have no more than two boundaries. Therefore there should only be two of these properties set to false within the object.

userAssociations object

Contains the user associations’ information.

userAssociations/restrictUserAccess Boolean

If true, only the assigned users will be able to mark/moderate candidate scripts. If false, the allocation of users serves only as a guide and anyone can mark/moderate candidate scripts.

userAssociations/enableMarker Boolean

Determines whether a specific user can be assigned as the marker at the point of scheduling.

userAssociations/requireMarker Boolean

Determines whether the allocation of a marker is mandatory at the point of scheduling.

userAssociations/enableModerator Boolean

Determines whether a specific user can be assigned as the moderator at the point of scheduling.

userAssociations/requireModerator Boolean

Determines whether the allocation of a moderator is mandatory at the point of scheduling.

isHtmlCompatible Boolean

Determines whether the Deliver in HTML Delivery setting is enabled. If true, the test will use the HTML test driver in delivery.

errors string

Information about any errors that occurred during the request.

serverTimeZone enumeration

The timezone of the server sending the response.

Listing a test’s associated test forms

get /api/v2/Test/{id}/TestForms

Send a request to the endpoint to retrieve a list of test forms associated with the test. Refer to the available parameters to influence the response. No request body is required.

Parameters

EXAMPLE: The endpoint /api/v2/Test/1/TestForms?scheduledTestFormsOnly=true would only return test forms associated with test 1 that are currently scheduled.

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
id	path OPTIONAL	`/api/v2/Test/{id}/TestForms`	Returns test form information for the specified test, where `{id}` is the test’s unique identifier.
reference	path OPTIONAL	`/api/v2/Test/{reference}/TestForms`	Returns test form information for the specified test, where `{reference}` is the test’s unique reference code.
reference	query OPTIONAL	`/api/v2/Test?reference={reference}`	Returns test form information for the specified test, where `{reference}` is the test’s unique reference code.
top	query OPTIONAL	`/api/v2/Test/{reference}/TestForms?$top={top}`	Defines number of responses to return when paging a response, where `{top}` is a number between 1 and 40.
skip	query OPTIONAL	`/api/v2/Test/{reference}/TestForms?$skip={skip}`	Defines how many responses to skip when paging a response, where `{skip}` is a number that should not exceed the total number of responses.
scheduledTestFormsOnly	query OPTIONAL	`/api/v2/Test/{id}/TestForms?scheduledTestFormsOnly={Boolean}`	If `{Boolean}` is `true`, only test forms currently scheduled are returned, where `{id}` is the test’s unique identifier (or reference code).

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top and skip parameters are joined using &. For example, the endpoint /api/v2/Test/1/TestForms?$top=10&scheduledTestFormsOnly would return the top 10 test forms associated with test 1 that are currently scheduled.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.

{
    "count": 3,
    "top": 10,
    "skip": 0,
    "pageCount": 1,
    "nextPageLink": null,
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "reference": "TestForm1",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1",
            "status": "Live",
            "valid": true
        },
        {
            "id": 2,
            "reference": "TestForm2",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/2",
            "status": "Live",
            "valid": true
        },
        {
            "id": 3,
            "reference": "TestForm3",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/3",
            "status": "Live",
            "valid": true
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Creating a test

post /api/v2/Test

Send a request to the endpoint to create a test.

Parameters

Name	Parameter	Input	Description
authorization	header MANDATORY	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
content-type	header MANDATORY	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
content-length	header MANDATORY	`{number}`	Determines the number of characters passed in the body of the request, where `{number}` is a numerical figure. This is usually automatically calculated when the request is sent.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.

Sample request

The following request contains the minimum required request body to create a test.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Final Year Geography Test",
    "reference": "Test1"
}

EXAMPLE: In this sample request, a draft test named ‘Final Year Geography Test’ is created.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

subject object mandatory

Contains the subject that the test is in.

subject/id integer

The subject’s unique identifier.

subject/reference string

The subject’s unique reference code.

name string mandatory

The test’s name.

reference string mandatory

The test’s unique reference code.

status enumeration optional

certifiedAccessible Boolean optional

Determines whether the JAWS screen reader is enabled for legacy tests. Defaults to false if omitted.

useAsTemplate Boolean optional

Determines whether the test can be used as a template for cloning. For more information, read Cloning tests. Defaults to false if omitted.

ExamType enumeration optional

Determines the type of test. The available options are:

ComputerBasedTest – A single-sitting assessment measured in minutes or hours.
ComputerBasedProject – A long-term assessment measured in days or weeks. Candidates can log into their test at any time between the start and end dates. Computer based projects must be taken in web delivery. For more information, read Creating a computer based project.

Defaults to ComputerBasedTest if omitted.

allowTimeExtensionWhileinProgress Boolean optional

Determines whether the Allow Time Extension While In Progress setting is enabled. If true, allows invigilators to add up to 24 hours to the duration of In Progress tests. Defaults to false if omitted.

attemptAutoSubmit Boolean optional

If false is cleared, Surpass automatically voids tests not submitted in time. Defaults to true if omitted.

resultsUploadGracePeriod integer optional

Sets the amount of days that Surpass waits before automatically voiding tests that have not been submitted. Defaults to 14 if omitted.

NOTE: attemptAutoSubmit must also be set to true.

requiresSecureClient Boolean optional

Determines whether the Requires SecureClient setting is enabled. If true, the test cannot be delivered in a web browser. Defaults to true if omitted.

requiresBYODMode Boolean optional

Determines whether the Requires BYOD Mode setting is enabled. If true, candidates must sit the test in BYOD SecureClient. For more information, speak to your Surpass Account Manager. Defaults to false if omitted.

IMPORTANT: The requiresSecureClient property must be true, and secureClientMode set to Locked. enableCandidateLogging must also be true.

secureClientMode enumeration optional

Sets the SecureClient delivery mode:

Unlocked – Allows candidates to minimise SecureClient and browse their device and/or the internet freely.
Locked – Prevents candidates leaving SecureClient during the test.

Defaults to Locked if omitted.

requiresInvigilation Boolean optional

Defaults to true if omitted.

certifiedForTabletDelivery Boolean optional

Determines whether the Certified for Tablet Delivery setting is enabled. If true, the test will be delivered in the SurpassDelivery tablet app. Defaults to false if omitted.

numberOfResits integer optional

If set to 0, candidates cannot resit a test after their first attempt. Defaults to null if omitted (and therefore Limit Resits is disabled).

validFromDate string optional

Sets the Valid From date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format. Defaults to present day if omitted.

expiryDate string optional

Sets the Expiry date for the date range in which the test can be scheduled for candidates, in YYYY/MM/DD format. Defaults to 10 years if omitted.

testWindowStartTime string optional

Sets the Start Time for the period of time in which candidates can enter the test on any given day, in HH:MM format. Defaults to 00:00 if omitted.

testWindowEndTime string optional

Sets the End Time for the period of time in which candidates can enter the test on any given day, in HH:MM format. Defaults to 23:59 if omitted.

randomiseTestForms Boolean optional

Determines whether the Randomise Test Forms setting is enabled. If true, distributes test forms in a random order to candidates if there is more than one form of the same test. Defaults to true if omitted.

allowTestFormRecycling Boolean optional

deliveryOptions enumeration optional

Determines the test delivery options available to Test Administration users. The available options are:

DeliverSameExamToAllCandidates – If a test has multiple test forms, candidates receive the same test form. If the test form has dynamic sections, the rules are run once to create a static test form that is delivered to all candidates.
DeliverDifferentExamsToAllCandidates – If a test has multiple test forms, candidates receive different test forms. If a given test form has dynamic sections, the rules are run as many times as necessary to create a unique test form for each candidate.
Either– Allows Test Administration users to decide whether to deliver the same test or different tests at the point of scheduling.

Defaults to DeliverDifferentExamsToAllCandidates if omitted.

testDistribution enumeration optional

Must pass as Online: tests can only be delivered online and must be scheduled in Surpass.

NOTE: This is a retired property and has no bearing on tests.

markingType enumeration optional

Determines how the test will be marked in Test Administration. The available options are:

StandardMarking – Makes the test available for marking in either the Surpass Mark screen or SecureMarker.
Psychometric – Enables psychometric references for ContentProducer items.
PaperMarking – Makes the test available for marking in the Surpass Paper Mark screen.

Defaults to StandardMarking if omitted.

candidateDetails object optional

Contains the Requires User Details confirmation settings’ information.

candidateDetails/required Boolean

Determines whether the Requires User Details confirmation setting is enabled. If true, forces candidates to confirm their personal details before starting the test. Defaults to true if omitted.

candidateDetails/duration integer

The time limit for candidates to confirm their details, in minutes. The accepted value range is 0–60. A value of 0 (or null) gives candidates unlimited time to confirm their details. Defaults to null if omitted.

NDA object optional

Contains the Candidate Agreement settings’ information.

NDA/required Boolean

Determines whether the Candidate Agreement setting is enabled. If true, forces candidates to agree to terms before starting the test. Defaults to true if omitted.

NDA/duration integer

The time limit for candidates to agree to the terms, in minutes. The accepted value range is 0–60. A value of 0 (or null) gives candidates unlimited time agree to the terms. Defaults to null if omitted.

NDA/confirmationText string

The candidate agreement terms in text format. Defaults to ‘By ticking this box you confirm your details are correct and you accept the awarding organisation’s code of conduct.’ if omitted.

progressBar object optional

Contains the progress bar settings’ information.

progressBar/required Boolean

Determines whether the Show Test Progress setting is enabled. If true, displays the progress bar to candidates. The progress bar shows candidates where they are in the test. Defaults to true if omitted.

progressBar/mode enumeration

Determines the progress bar’s mode. The available options are:

ItemBased – Displays candidate progress based on how many items they have attempted versus the total number of items in the test. For example, if there are 10 items in a test and a candidate has attempted six, their progress is displayed as 60%.
MarksBased – Displays candidate progress based on how many marks are in the items they have answered versus the total number of marks in the test. For example, if a test has five Multiple Choice questions worth one mark each and an Essay question worth ten marks, the progress bar will go up 6.66% with each Multiple Choice question answered.
2 (Item based fraction text) – Displays candidate progress as a fraction, with the number of attempted questions over the total number of questions in the test. For example, if there are twelve questions in a test and a candidate has answered three, the candidate will see ‘3/12 Items Attempted’.

Defaults to MarksBased if omitted.

testStyle enumeration optional

Determine the test’s navigation style. The available options are:

CustomBranding – Candidates can move freely through the test.
CustomBrandingForwardOnly – Candidates can only move to the next item.

Defaults to CustomBranding if omitted.

styleProfile object optional

Contains the test profile’s information. For more information on test profiles, read About the Test Profiles screen.

styleProfile/testProfile object

Contains the test profile’s information.

styleProfile/testProfile/id integer

The test profile’s unique identifier. Defaults to null if omitted.

styleProfile/displayReport Boolean

Determines whether the Display Report setting is enabled. If true, allows candidates to view a score report after a test. Defaults to false if omitted.

styleProfile/displayReportPrintButton Boolean

Determines whether the Display Report Print Button setting is enabled. If true, allows the score report to be printed. Defaults to false if omitted.

defaultNavigationLanguage enumeration optional

Determines the language used for the test driver’s interface and menus. This does not affect item content. For a list of all available languages, read About Surpass test languages. Defaults to English if omitted.

allowLanguageOverride Boolean optional

showPageRequiresScrollingAlert Boolean optional

NOTE: HTML tests have a built-in scrolling alert that is enabled by default.

easyPvalue integer optional

The minimum Easy P value. For more information on P values, read ‘P Value Ranges’ in About test settings. Defaults to 0.700 if omitted.

maxEasyPvalue integer optional

The maximum Easy P value. For more information on P values, read ‘P Value Ranges’ in About test settings. Defaults to 0.900 if omitted.

hardPvalue integer optional

The maximum Hard P value. For more information on P values, read ‘P Value Ranges’ in About test settings. Defaults to 0.300 if omitted.

minHardPvalue integer optional

The minimum Hard P value. For more information on P values, read ‘P Value Ranges’ in About test settings. Defaults to 0.100 if omitted.

generateTestStatistics Boolean optional

NOTE: This is a retired property and has no bearing on tests.

allowPackagingOfCandidateResponses Boolean optional

automaticallyShowToCentre Boolean optional

Determines whether the Automatically Show To Centre setting is enabled.

NOTE: This is a retired property and has no bearing on tests.

autoCreatePIN Boolean optional

If Requires Invigilation is enabled and this property is false, invigilators must manually unlock candidates’ tests.

strictControlReasonableAdjustments Boolean optional

NOTE: This only affects users with the Add extra time to tests with strict control for reasonable adjustments permission.

enableCandidateLogging Boolean optional

Determines whether the Enable Candidate Logging setting is enabled. If true, enables a secure log of candidates’ interactions in the test. This log can only be viewed in the database. Defaults to false if omitted.

WARNING: Candidate logs can take up space in the database and this may result in charges for extra storage.

scoreBoundaries object optional

scoreBoundaries/type enumeration

Determines whether the score boundaries are Percentage or Results-based. Defaults to Percentage if omitted.

scoreBoundaries/boundaries array

Contains each score boundary’s information.

NOTE: A separate object must be passed for each score boundary. If omitted, defaults to four High Marking Item Boundaries ('Not met', 'Close to met', 'Met', and 'Exceeded') and two Low Marking Item Boundaries ('Met' and 'Not met').

scoreBoundaries/boundaries/modifier enumeration

Determines the score boundary’s modifier. This can be either less than (lt) or greater than (gt).

scoreBoundaries/boundaries/value integer

The score boundary’s value (percentage).

scoreBoundaries/boundaries/description string

The score boundary’s name. For example, ‘Not met’.

scoreBoundaries/boundaries/higherBoundary Boolean

Determines whether score boundary is a high marking item boundary.

TIP: Low Marking Item Boundaries should have no more than two boundaries. Therefore there should only be two of these properties set to false within the object.

userAssociations object optional

Contains the user associations’ information.

userAssociations/restrictUserAccess Boolean

If true, only the assigned users will be able to mark/moderate candidate scripts. If false, the allocation of users serves only as a guide and anyone can mark/moderate candidate scripts. Defaults to false if omitted.

userAssociations/enableMarker Boolean

Determines whether a specific user can be assigned as the marker at the point of scheduling. Defaults to false if omitted.

userAssociations/requireMarker Boolean

Determines whether the allocation of a marker is mandatory at the point of scheduling. Defaults to false if omitted.

userAssociations/enableModerator Boolean

Determines whether a specific user can be assigned as the moderator at the point of scheduling. Defaults to false if omitted.

userAssociations/requireModerator Boolean

Determines whether the allocation of a moderator is mandatory at the point of scheduling. Defaults to false if omitted.

isHtmlCompatible Boolean optional

Determines whether the Deliver in HTML Delivery setting is enabled. If true, the test will use the HTML test driver in delivery. Defaults to true if omitted.

NOTE: Tests created in HTML subjects must set this property to true; if passed as false, it will be overridden to true. Tests created in mixed subjects can set this property to true, but all item content must be compatible with HTML for successful test delivery.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new test’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/Test/1",
    "errors": null,
}

Error Codes

Refer to the following table for information on error codes that may be encountered when using this resource.

Name	Code	Description
InternalServer	1	Internal server error.
Unauthorized	3	The request has been sent by an unauthorised user.
IncorrectFieldFormat	4	A field in the request has not been completed in the correct format.
InaccessibleOperation	5	The request has been sent by a user with invalid permissions.
InaccessibleData	6	The request has been sent by a user with invalid permissions.
MissingBody	7	There is an issue with the request body.
InvalidReference	11	The unique reference code used in the request is invalid.
InvalidInputParameters	15	There is an issue with the path or query parameters.
InvalidId	16	The ID number used in the request is invalid.
InvalidODataOperation	19	There is an issue with the query parameters.
BadRequest	20	There is an issue with the `/api/v2/Test?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.

Test API

In This Article

Listing tests

Parameters

Sample response

Response schema

Retrieving test information

Parameters

Sample response

Response schema

Listing a test’s associated test forms

Parameters

Sample response

Response schema

Creating a test

Parameters

Sample request

Request body schema

Sample response

Error Codes

Further reading

About the site