TestSession API
Test sessions can be invigilated and using the Surpass API. Once released or voided, test sessions become result entities. Marks or Multiple Choice responses can also be assigned to paper test sessions.
The TestSession API resource is used to list and retrieve test sessions, update and reset test session states, and assign marks to questions taken on paper.
This article explains what calls can be made to the Surpass API using the TestSession resource.
Import this API into your Postman Workspace
In This Article
Listing test sessions
Send a request to the endpoint to list test sessions. 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.
|
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/TestSession?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number greater than 0. |
|
skip |
query OPTIONAL |
/api/v2/TestSession?$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/TestSession?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of candidate/id, candidate/reference, centre/id, centre/reference, test/id, test/reference, testForm/id, testForm/reference, scheduledTo, scheduledFrom, state, {operator} is eq (equal to), and {value} is the integer, string (in DD/MM/YYYY HH:MM format for dates and times), or enumeration (see currentExamState property in the response schema for available state inputs) the filter query looks for an exact match for in the request. For a greater than query: {filter} is creationDate, lastInteractionDate, lastUpdatedDate, startDate, endDate, testActivatedInfo/startedDate, testActivatedInfo/submittedDate, {operator} is ge (greater than), and {value} is the string (in DD/MM/YYYY HH:MM format) the filter query looks for more than in the request. For a less than query: {filter} is creationDate, lastInteractionDate, lastUpdatedDate, startDate, endDate, testActivatedInfo/startedDate, testActivatedInfo/submittedDate, {operator} is le (less than), and {value} is the string (in DD/MM/YYYY format) the filter query looks for less than in the request. |
|
showMarkingProgress |
query OPTIONAL |
/api/v2/TestSession?showMarkingProgress={Boolean} |
Determines whether to only include test sessions in Awaiting Marking (AwaitingMarking) state and marking progress information in the response, where {Boolean} is one of true or false. |
|
includeAdditionalInfo |
query OPTIONAL |
/api/v2/TestSession?includeAdditionalInfo={Boolean} |
Determines whether to include candidate, centre, and additional test session information in the response, where {Boolean} is one of true or false. |
|
showTestForm |
query OPTIONAL |
/api/v2/TestSession?showTestForm={Boolean} |
Determines whether to include test form information in the response, where {Boolean} is one of true or false. |
|
showTest |
query OPTIONAL |
/api/v2/TestSession?showTest={Boolean} |
Determines whether to include test information in the response, where {Boolean} is one of true or false. |
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": 144,
"top": 10,
"skip": 0,
"pageCount": 15,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/TestSession?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "9QY4V44S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/1"
},
{
"id": 2,
"reference": "YXCTX44S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/2"
},
{
"id": 3,
"reference": "GK7JD94S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/3"
},
{
"id": 4,
"reference": "9J6G834S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/4"
},
{
"id": 5,
"reference": "LYVQBP4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/5"
},
{
"id": 6,
"reference": "QWKB7B4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/6"
},
{
"id": 7,
"reference": "NBJKQM4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/7"
},
{
"id": 8,
"reference": "FL8QGV4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/8"
},
{
"id": 9,
"reference": "YML63Y4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/9"
},
{
"id": 10,
"reference": "J7KMCQ4S",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/10"
}
],
"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 test sessions there are in total.
top integer
Details number of test sessions returned in the response.
skip integer
Details how many test sessions were skipped to display those in the response.
pageCount integer
Details how many pages of test sessions there are.
nextPageLink string
The endpoint to call the next page of test sessions. If null, the response is the last page of test sessions.
prevPageLink string
The endpoint to call the previous page of test sessions. If null, the response is the first page of test sessions.
response array
Contains the rest of the response.
id integer
The test session’s unique identifier.
reference string
The test session’s unique reference code.
href string
The endpoint to call the test session’s information, such as /api/v2/TestSession/{id} where {id} is the test session’s unique identifier.
awaitingMarkingSubmission Boolean
Determines whether the test has been marked and is awaiting to be submitted.
markingProgressPercent integer
The marking progress for the script as a percentage.
candidate object
Contains the candidate’s information.
candidate/id integer
The candidate’s unique identifier.
candidate/href string
The endpoint to call the candidate’s information, such as /api/v2/Candidate/{id} where {id} is the candidate’s unique identifier.
testForm object
Contains the test form’s information.
testForm/id integer
The test form’s unique identifier.
testForm/reference string
The test form’s unique reference code.
testForm/name string
The test form’s name.
testForm/href string
The endpoint to call the test form’s information, such as /api/v2/TestForm/{id} where {id} is the test form’s unique identifier.
centre object
Contains the centre’s information.
centre/id integer
The centre’s unique identifier.
centre/href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
test object
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/name string
The test’s name.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
currentExamState enumeration
The test session’s current state. Refer to the table of test session states below this section for all possible test session states.
downloadedToSecureClient Boolean
Determines whether the test has been downloaded to SecureClient. For more information, read Downloading a test to take later in SecureClient.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Test session states table
The following table contains a description of every test session state.
| State No. | State Name | Description |
|---|---|---|
|
1 |
ScheduledButNotCreated |
The test has been scheduled, but its content not yet retrieved. |
|
2 |
ScheduledButNotDownloaded |
The Pre-session Download Window has opened but the test has not yet been downloaded.
NOTE: This is a temporary state between the test session being ScheduledButNotCreated and ScheduledButLocked.
|
|
3 |
ScheduledButLocked |
The test form has been generated. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session. Test sessions remain locked until the test window opens. |
|
4 |
Ready |
The test window is open and the test is ready to be sat by the candidate. |
|
5 |
LockedForInvigilator |
The invigilator needs to manually unlock the test session. |
|
6 |
InProgress |
The test session is in progress. |
|
7 |
Paused |
The test session has been paused by an invigilator. |
|
8 |
Offline |
NOTE: This is a retired state.
|
|
9 |
Finished |
The test session is finished.
NOTE: This is a temporary state between the candidate finishing their test and their script moving through to either AwaitingMarking or Archived.
|
|
10 |
Voided |
The test session has been voided. |
|
11 |
Marked |
The candidate’s script has been marked.
NOTE: This is a temporary state between marking being finished and the script moving through to either Moderate (AwaitingVerification) or Audit (Archived).
|
|
12 |
ScriptVerified |
The candidate’s script is being submitted.
NOTE: This is a temporary state between the script becoming Archived after being released from Mark (AwaitingMarking), or to Moderate (AwaitingVerification) from Mark.
|
|
13 |
Archived |
The test session is warehoused in Audit. |
|
14 |
LockedByPin |
The test session is awaiting the candidate to enter the session’s PIN. |
|
15 |
AwaitingMarking |
The candidate’s script is waiting to be marked. |
|
16 |
AwaitingVerification |
The candidate’s script is waiting to be moderated. |
| 17 | N/A |
The test session was delivered on paper and the candidate’s results uploaded using Upload OMR Results. OMR uploaded scripts are automatically warehoused (Archived). |
|
18 |
AwaitingUpload |
The test session was downloaded to SecureClient but has not yet been uploaded back into Surpass. |
|
19 |
PaperResponseUpload |
The test session is being delivered on paper and the candidate’s results are yet to be uploaded. |
|
99 |
Exception |
The test has failed to move between states and a manual intervention by the Surpass support team is required. |
Retrieving test session information
Send a request to the endpoint to retrieve information for a specific test session using either its ID or the candidate’s keycode. 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.
|
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/TestSession/{id} |
Returns information for the specified test session, where {id} is the test session’s unique identifier. |
|
keycode |
path OPTIONAL |
/api/v2/TestSession/{keycode} |
Returns information for the specified test session, where {keycode} is the candidate’s unique keycode. |
|
returnDownloadData |
query OPTIONAL |
/api/v2/TestSession/{id}?returnDownloadData={Boolean} |
Determines whether to include test session download data in the response, where {id} is the test session’s unique identifier (or candidate’s unique keycode), and {Boolean} is one of true or false. |
|
returnAdditionalInformation |
query OPTIONAL |
/api/v2/TestSession/{id}?returnAdditionalInformation={Boolean} |
Determines whether to include candidate, centre, and additional test session information in the response, where {id} is the test session’s unique identifier (or candidate’s unique keycode), and {Boolean} is one of true or false. |
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": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/1",
"keycode": "94N69JX8",
"testState": "Ready",
"test": {
"id": 1,
"reference": "Test1",
"name": "Final Year Geography Test",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Test/1"
},
"centre": {
"id": 1,
"reference": "Centre1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
},
"candidate": {
"id": 1,
"reference": "Candidate1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1"
},
"creationDate": "15/01/2022",
"startDate": "20/01/2022",
"endDate": "20/01/2022",
"startTime": "10:30",
"endTime": "15:00",
"testForm": {
"id": 1,
"reference": "TestForm1",
"name": "Final Year Geography Test Form January 2022",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestForm/1"
},
"localState": null,
"duration": 60,
"requiresInvigilation": true,
"externalReference": null,
"testActivatedInfo": {
"started": false
},
"downloadedToSecureClient": false,
"requiresCheckIn": false,
"files": [],
"pin": "9T3B9F"
}
],
"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 test sessions there are in total. This is null because the information retrieved is for a specific test session.
top integer
Details number of test sessions returned in the response. This is null because the information retrieved is for a specific test session.
skip integer
Details how many test sessions were skipped to display those in the response. This is null because the information retrieved is for a specific test session.
pageCount integer
Details how many pages of test sessions there are. This is null because the information retrieved is for a specific test session.
nextPageLink string
The endpoint to call the next page of test sessions. This is null because the information retrieved is for a specific test session.
prevPageLink string
The endpoint to call the previous page of test sessions. This is null because the information retrieved is for a specific test session.
response array
Contains the rest of the response.
id integer
The test session’s unique identifier.
href string
The endpoint to call the test session’s information, such as /api/v2/TestSession/{id} where {id} is the test session’s unique identifier.
keycode string
The candidate’s unique keycode, used to enter their test.
testState enumeration
The test session’s current state. Refer to the table of test session states below this section for all possible test session states.
downloadedToSecureClient Boolean
Determines whether the test has been downloaded to SecureClient. For more information, read Downloading a test to take later in SecureClient.
test object
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/name string
The test’s name.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
centre object
Contains the centre’s information.
centre/id integer
The centre’s unique identifier.
centre/reference string
The centre’s unique reference code.
centre/href string
The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.
candidate object
Contains the candidate’s information.
candidate/id integer
The candidate’s unique identifier.
candidate/reference string
The candidate’s unique reference code.
candidate/href string
The endpoint to call the candidate’s information, such as /api/v2/Candidate/{id} where {id} is the candidate’s unique identifier.
creationDate string
The date the test session was created, in DD/MM/YYYY format.
startDate string
The test session’s Start Date, in DD/MM/YYYY format.
endDate string
The test session’s End Date, in DD/MM/YYYY format.
startTime string
The test session’s Start Time, in HH:MM format.
endTime string
The test session’s End Time, in HH:MM format.
testForm object
Contains the test form’s information.
testForm/id integer
The test form’s unique identifier.
testForm/reference string
The test form’s unique reference code.
testForm/name string
The test form’s name.
testForm/href string
The endpoint to call the test form’s information, such as /api/v2/TestForm/{id} where {id} is the test form’s unique identifier.
localState enumeration
duration integer
The test session’s duration.
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.
externalReference string
An external reference used for cross-referencing between systems. This can also be extracted via the Result API.
testActivatedInfo object
Contains the test session’s information, including the date and time of the test being taken by the candidate if they have started it.
testActivatedInfo/startedDate string
The date and time the candidate started the test, in YYYY-MM-DDTHH:SS format.
testActivatedInfo/submittedDate string
The date and time the candidate submitted the test, in YYYY-MM-DDTHH:SS format.
testActivatedInfo/started Boolean
Determines whether the test session has been started. If false, the test session has not been started and the testActivatedInfo/startedDate and testActivatedInfo/submittedDate properties are not returned.
downloadedToSecureClient Boolean
Determines whether the test has been downloaded to SecureClient. For more information, read Downloading a test to take later in SecureClient.
downloads array
Contains the download data if the test has been downloaded to SecureClient. For more information, read Downloading a test to take later in SecureClient.
downloads/os string
The operating system used to download the test.
downloads/ipAddress string
The IP address used to download the test.
downloads/machineName string
The name of the machine used to download the test.
downloads/dateTime string
The date and time the test was downloaded, in HH:MM:SS Day DD Month YYYY format.
downloads/local Boolean
downloads/userName string
The username of the user who downloaded the test.
requiresCheckIn Boolean
files array
pin string
The test session’s PIN.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Test session states table
The following table contains a description of every test session state.
| State No. | State Name | Description |
|---|---|---|
|
1 |
ScheduledButNotCreated |
The test has been scheduled, but its content not yet retrieved. |
|
2 |
ScheduledButNotDownloaded |
The Pre-session Download Window has opened but the test has not yet been downloaded.
NOTE: This is a temporary state between the test session being ScheduledButNotCreated and ScheduledButLocked.
|
|
3 |
ScheduledButLocked |
The test form has been generated. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session. Test sessions remain locked until the test window opens. |
|
4 |
Ready |
The test window is open and the test is ready to be sat by the candidate. |
|
5 |
LockedForInvigilator |
The invigilator needs to manually unlock the test session. |
|
6 |
InProgress |
The test session is in progress. |
|
7 |
Paused |
The test session has been paused by an invigilator. |
|
8 |
Offline |
NOTE: This is a retired state.
|
|
9 |
Finished |
The test session is finished.
NOTE: This is a temporary state between the candidate finishing their test and their script moving through to either AwaitingMarking or Archived.
|
|
10 |
Voided |
The test session has been voided. |
|
11 |
Marked |
The candidate’s script has been marked.
NOTE: This is a temporary state between marking being finished and the script moving through to either Moderate (AwaitingVerification) or Audit (Archived).
|
|
12 |
ScriptVerified |
The candidate’s script is being submitted.
NOTE: This is a temporary state between the script becoming Archived after being released from Mark (AwaitingMarking), or to Moderate (AwaitingVerification) from Mark.
|
|
13 |
Archived |
The test session is warehoused in Audit. |
|
14 |
LockedByPin |
The test session is awaiting the candidate to enter the session’s PIN. |
|
15 |
AwaitingMarking |
The candidate’s script is waiting to be marked. |
|
16 |
AwaitingVerification |
The candidate’s script is waiting to be moderated. |
| 17 | N/A |
The test session was delivered on paper and the candidate’s results uploaded using Upload OMR Results. OMR uploaded scripts are automatically warehoused (Archived). |
|
18 |
AwaitingUpload |
The test session was downloaded to SecureClient but has not yet been uploaded back into Surpass. |
|
19 |
PaperResponseUpload |
The test session is being delivered on paper and the candidate’s results are yet to be uploaded. |
|
99 |
Exception |
The test has failed to move between states and a manual intervention by the Surpass support team is required. |
Retrieving test session file information
Updating a test session’s state
Send a request to the endpoint to update a specific test session’s state.
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.
|
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. |
|
id |
path OPTIONAL |
/api/v2/TestSession/{id} |
Update specified test session, where {id} is the test session’s unique identifier. |
|
keycode |
path OPTIONAL |
/api/v2/TestSession/{keycode} |
Update specified test session, where {keycode} is the candidate’s unique keycode. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update a specific test session. Refer to the request body schema for all properties that can be updated.
{
"testState": "Voided",
"voidReason": "Withdrawn"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
testState enumeration
The test session’s state. Refer to the table of test session states below this section for all possible test session states.
voidReason enumeration
The reason the test is being voided. The available options are NotYetStarted, Absent, Withdrawn, PartiallyCompleted, and Other.
voidMessage string
The reason the test is being voided if the voidReason property is Other.
forceLocalVoid Boolean
offlineDelivery Boolean
Test session states table
The following table contains a description of every test session state.
| State No. | State Name | Description |
|---|---|---|
|
1 |
ScheduledButNotCreated |
The test has been scheduled, but its content not yet retrieved. |
|
2 |
ScheduledButNotDownloaded |
The Pre-session Download Window has opened but the test has not yet been downloaded.
NOTE: This is a temporary state between the test session being ScheduledButNotCreated and ScheduledButLocked.
|
|
3 |
ScheduledButLocked |
The test form has been generated. Test form content and settings (including item content) are locked once generated and cannot be edited for the scheduled test session. Test sessions remain locked until the test window opens. |
|
4 |
Ready |
The test window is open and the test is ready to be sat by the candidate. |
|
5 |
LockedForInvigilator |
The invigilator needs to manually unlock the test session. |
|
6 |
InProgress |
The test session is in progress. |
|
7 |
Paused |
The test session has been paused by an invigilator. |
|
8 |
Offline |
NOTE: This is a retired state.
|
|
9 |
Finished |
The test session is finished.
NOTE: This is a temporary state between the candidate finishing their test and their script moving through to either AwaitingMarking or Archived.
|
|
10 |
Voided |
The test session has been voided. |
|
11 |
Marked |
The candidate’s script has been marked.
NOTE: This is a temporary state between marking being finished and the script moving through to either Moderate (AwaitingVerification) or Audit (Archived).
|
|
12 |
ScriptVerified |
The candidate’s script is being submitted.
NOTE: This is a temporary state between the script becoming Archived after being released from Mark (AwaitingMarking), or to Moderate (AwaitingVerification) from Mark.
|
|
13 |
Archived |
The test session is warehoused in Audit. |
|
14 |
LockedByPin |
The test session is awaiting the candidate to enter the session’s PIN. |
|
15 |
AwaitingMarking |
The candidate’s script is waiting to be marked. |
|
16 |
AwaitingVerification |
The candidate’s script is waiting to be moderated. |
| 17 | N/A |
The test session was delivered on paper and the candidate’s results uploaded using Upload OMR Results. OMR uploaded scripts are automatically warehoused (Archived). |
|
18 |
AwaitingUpload |
The test session was downloaded to SecureClient but has not yet been uploaded back into Surpass. |
|
19 |
PaperResponseUpload |
The test session is being delivered on paper and the candidate’s results are yet to be uploaded. |
|
99 |
Exception |
The test has failed to move between states and a manual intervention by the Surpass support team is required. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated test session’s details.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}Resetting a test session’s state
Send a request to the endpoint to reset a test session’s state back to state 1 (scheduledButNotCreated) using the test form’s unique reference code. No request body is required.
This allows the test to be re-downloaded in case any test form content and settings (including item content) have been updated since the test form was downloaded. The test form being used in the test session can also be changed.
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.
|
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. |
|
keycode |
path MANDATORY |
/api/v2/TestSession/{keycode} |
Reset specified test session’s state, where {keycode} is the candidate’s unique keycode.
NOTE: The currentTestFormRef and updatedTestFormRef query parameters must also be passed in the request.
|
|
currentTestFormRef & updatedTestFormRef |
query MANDATORY |
/api/v2/TestSession/{keycode}?currentTestFormRef={reference}&updatedTestFormRef={reference} |
Reset specified test session’s state, where {keycode} is the candidate’s unique keycode, {reference} is the unique reference code of the test form being updated, and {reference} is the replacement form’s unique reference code.
TIP: Use the same test form reference code for both parameters to keep the same test form.
|
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the test session has been reset by returning a null id.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}Assigning item marks or Multiple Choice responses
Send a request to the endpoint to assign item marks, or responses to Multiple Choice questions, to paper tests.
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.
|
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. |
|
keycode |
path MANDATORY |
/api/v2/TestSession/{keycode} |
Assign item marks or Multiple Choice responses to specified test session, where {keycode} is the candidate’s unique keycode.
NOTE: One of the ItemMarks or ItemResponses path parameters must also be passed in the request.
|
|
ItemMarks |
path OPTIONAL |
/api/v2/TestSession/{keycode}/ItemMarks |
Assign item marks to specified test session, where {keycode} is the candidate’s unique keycode. |
|
ItemResponses |
path OPTIONAL |
/api/v2/TestSession/{keycode}/ItemResponses |
Assign Multiple Choice responses to specified test session, where {keycode} is the candidate’s unique keycode. |
|
scannedItemResponses |
path OPTIONAL |
/api/v2/TestSession/{keycode}/ScannedItemResponses |
NOTE: This is a retired path parameter and should therefore not be used.
|
|
completionDate |
query OPTIONAL |
/api/v2/TestSession/{keycode}/ItemMarks?completionDate={date} |
Add a completion date to specified test session, where {keycode} is the candidate’s unique keycode and {date} is the completion date in DD/MM/YYYY format.
TIP: This is useful for if the date the test was sat differs from the date the item marks or Multiple Choice responses are being uploaded.
|
|
markInSecureMarker |
query OPTIONAL |
/api/v2/TestSession/{keycode}/ScannedItemResponses?markInSecureMarker={Boolean} |
NOTE: This is a retired path parameter and should therefore not be used.
|
Sample request
The following request contains the minimum required request body to assign marks to a test session.
[
{
"questionNumber": "1",
"mark": "1"
},
{
"questionNumber": "2",
"mark": "0"
}
]The following request contains the minimum required request body to assign Multiple Choice responses to a test session.
[
{
"questionNumber": "1",
"answer": "A"
},
{
"questionNumber": "2",
"answer": "C"
}
]Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
questionNumber integer mandatory
The question number.
mark integer optional
The mark assigned to the question.
answer string optional
The answer option assigned to the question. Multiple Response question responses can be separated by the pipe symbol (for example, A|C|D).
imagePath string optional
isCoverSheet Boolean optional
order integer optional
itemIDs array optional
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated test session’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSession/1",
"errors": null,
"serverTimeZone": null
}Uploading scanned responses
Submitting a marked test
Send a request to the endpoint to update a specific test session from AwaitingMarking state to Marked. 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.
|
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/TestSession/{id}/SubmitMarkedExam |
Update specified test session, where {id} is the test session’s unique identifier. |
|
keycode |
path OPTIONAL |
/api/v2/TestSession/{keycode}/SubmitMarkedExam |
Update specified test session, where {reference} is the candidate’s unique keycode. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated test session’s details.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": 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. |
|
InaccessibleCandidate |
13 |
The candidate defined in the request cannot be accessed. |
|
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/TestSession?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
ChangingTestSessionStateCannotUpdateState |
68 |
The test session state could not be updated. This may be because the test session’s current state is not eligible to be moved to the specified state. |
|
ChangingTestSessionStateUnknownError |
69 |
The test session state could not be updated. |
|
ChangingTestSessionStateDatabaseError |
70 |
The test session state could not be updated because of a database error. |
|
ChangingTestSessionStateInsufficientPermissions |
71 |
The test session state could not be updated because the request has been sent by a user with invalid permissions. |
|
ChangingTestSessionStateErrorMovingState |
72 |
There is an issue with the test session moving between states. |
| ChangingTestSessionStateAssessmentIsNotValid |
73 |
The specified test session is invalid. |
| ChangingTestSessionStateXmlError |
74 |
There is an issue with the request body XML. |
| ExamNotInAwaitingMarkingState |
224 |
The specified test session needs to be in AwaitingMarking state. |
| ExamNotHumanMarkingComplete |
225 |
The specified test session has not been marked. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: