TestSchedule API
Test sessions are scheduled for particular candidates on a specific date and time. Before scheduling a test, you must have a test and at least one test form and at least one candidate associated with the test’s parent subject.
The TestSchedule API resource is used to schedule and delete test sessions.
This article explains what calls can be made to the Surpass API using the TestSchedule resource.
Import this API into your Postman Workspace
Scheduling a test session
Send a request to the endpoint to schedule a candidate for a test session. Successful responses contain the candidate’s keycode and the test session’s PIN.
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. |
|
autoSyncCentreSubject |
header OPTIONAL |
{Boolean} |
If {Boolean} is true, associates candidates with the subject that contains the test you are scheduling. |
|
quickRegisterCandidate |
header OPTIONAL |
{Boolean} |
If {Boolean} is true, creates or updates the candidate specified in the request. See the Candidate property in the request schema for more details. |
Sample request
The following request contains the minimum required request body to schedule a candidate for a test session.
{
"Test": {
"id": 1
},
"Centre": {
"id": 1
},
"Candidate": {
"id": 1
},
"startDate": "11/02/2023",
"endDate": "11/02/2023",
"startTime": "1200",
"endTime": "1500"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
Test object mandatory
Contains the test’s information.
Test/id integer
The test’s unique identifier.
Test/reference string
The test’s unique reference code.
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 mandatory
Contains the centre’s information.
Centre/id integer
The centre’s unique identifier.
Centre/reference string
The centre’s unique reference code.
Candidate object mandatory
Contains the candidate’s information. Only Candidate/id or Candidate/reference are required to schedule a candidate.
Candidate/firstName string
The candidate’s first name.
Candidate/middleName string
The candidate’s middle name.
Candidate/lastName string
The candidate’s last name.
Candidate/dateOfBirth string
The candidate’s date of birth in DD/MM/YYYY format.
Candidate/gender enumeration
The candidate’s gender. The available inputs are Male, Female, or Unspecified. Defaults to Unspecified if omitted.
Candidate/email string
The candidate’s email address.
Candidate/tel string
The candidate’s telephone number.
Candidate/uln integer
The candidate’s Unique Learner Number (ULN). A ULN consists of 10 numbers, and its visibility is determined by a Site Setting. For more information, read About Site Settings options.
Candidate/reasonableAdjustments Boolean
Whether the candidate has been granted additional time during tests. Defaults to false if omitted.
Candidate/reasonableAdjustmentPercentage integer
If Candidate/reasonableAdjustments is set to true, you can apply a custom reasonable adjustment value to the candidate.
Candidate/isExternal Boolean
If set to true, the candidate can only be edited via the Surpass API. This prevents synchronisation issues where candidates also exist on databases external to Surpass. Defaults to false if omitted.
Candidate/expiryDate string
The candidate’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
Candidate/id integer
The candidate’s unique identifier.
Candidate/reference string
The candidate’s unique reference code.
startDate string mandatory
The Start Date on which the test will be available for candidates, in DD/MM/YYYY format.
endDate string mandatory
The End Date is the last day on which the test can be sat, in DD/MM/YYYY format.
startTime string mandatory
The test session’s Start Time, in HHMM format.
endTime string mandatory
The test session’s End Time, in HHMM format.
reasonableAdjustments object optional
This object modifies the candidate’s test duration. Any candidate’s test duration can be modified, but candidates with Reasonable Adjustments (Candidate/reasonableAdjustments) enabled are granted additional time automatically.
The maximum extra time allowed to be given to candidates is determined at the test form level.
reasonableAdjustments/extraTimeMin integer
The length of extra time (in minutes) to give the candidate.
reasonableAdjustments/extraTimePercentage integer
The length of extra time (as a percentage of the test duration) to give the candidate.
reasonableAdjustments/reason string
Your reason for giving the candidate extra time.
markedExternally Boolean optional
If true, once completed the test bypasses marking in Surpass and instead moves to the Archived, warehoused state. Defaults to false if omitted.
allowMultipleOpenSessions Boolean optional
If true, Surpass logic is overridden to schedule the test even if the candidate is already scheduled for the test. Defaults to false if omitted.
requiresInvigilation Boolean optional
Determines whether the Requires Invigilation (requiresInvigilation) 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.
Defaults to the Requires Invigilation test level setting if omitted.
testTags array optional
Contains any tags to be added to the test session. Tags are displayed in the Invigilate screen. Tags cannot exceed 250 characters per tag.
TestForm object optional
Contains the test form’s information. Defaults to Automatic Selection (the system chooses a test form at random) if omitted.
TestForm/id integer
The test form’s unique identifier.
TestForm/reference string
The test form’s unique reference code.
Marker object optional
Contains the allocated marker’s information.
Marker/id integer
The allocated marker’s unique (user) identifier.
Marker/reference string
The allocated marker’s unique (user) reference code.
Moderator object optional
Contains the allocated moderator’s information.
Moderator/id integer
The allocated moderator’s unique (user) identifier.
Moderator/reference string
The allocated moderator’s unique (user) reference code.
purchaseOrder string optional
Stores an external invoice number against the test session.
breakReasonableAdjustments object optional
This object modifies the candidate’s test break duration. Any candidate’s test break duration can be modified, but candidates with the Candidate/reasonableAdjustments property set to true are granted additional time automatically.
The maximum extra time allowed to be given to candidates is determined at the test form level.
breakReasonableAdjustments/extraTimeMin integer
The length of extra break time (in minutes) to give the candidate.
breakReasonableAdjustments/extraTimePercentage integer
The length of extra break time (as a percentage of the test duration) to give the candidate.
breakReasonableAdjustments/numberOfExtraBreaksPerSection integer
The number of extra breaks to give the candidate.
breakReasonableAdjustments/reason string
Your reason for giving the candidate extra break time.
subject object optional
Contains the information for the subject the test belongs to.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
unscheduledBreak object optional
Contains the information of any unscheduled breaks.
unscheduledBreak/extraTimeMin integer
The amount of time the candidate can use for breaks. If 0, the candidate has no break time. Defaults to 0 if omitted.
language enumeration optional
Determines the language used for the test driver’s interface and menus. This does not affect item content. Defaults to en if omitted.
The available languages and their codes are:
- Amharic (amh)
- Arabic – UAE (ar)
- Armenian – Eastern (arm)
- Azerbaijani (az)
- Bulgarian (bul)
- Chinese – Simplified (zh)
- Chinese – Traditional (zho)
- Croatian (hrv)
- Czech (ces)
- Danish (dan)
- Dutch (nl)
- English – UK (en)
- English – US (us)
- Estonian (est)
- Farsi (per)
- Finnish (fin)
- French (fr)
- French – Canadian (frc)
- Gaelic – Irish (gle)
- Gaelic – Scottish (ga)
- Galician (glg)
- German (ge)
- Greek (gre)
- Hebrew (heb)
- Hungarian (hun)
- Indonesian (ind)
- Italian (ita)
- Japanese (jpn)
- Khmer (khm)
- Korean (kor)
- Lao (lao)
- Latvian (lav)
- Lithuanian (lit)
- Maltese (mlt)
- Nepali (nep)
- Norwegian (no)
- Polish (pol)
- Portuguese (por)
- Portuguese – Brazilian (pob)
- Punjabi (iir)
- Romanian (ron)
- Russian (rus)
- Samoan (smo)
- Slovak (slk)
- Slovenian (slv)
- Somali (som)
- Spanish (sp)
- Thai (tha)
- Turkish (tur)
- Ukrainian (ukr)
- Vietnamese (vie)
- Welsh (we)
enforceTimes Boolean optional
Determines whether a 24-hour buffer is applied to tests, allowing candidates to enter their test session 24 hours either side of the scheduled start time. Defaults to false if omitted.
uploadResponses Boolean optional
Determines whether the test is to be delivered outside of Surpass. If true, the test session is set to the PaperResponseUpload state and its responses must be uploaded using the TestSession API or the Upload Responses button in the Invigilate screen. Defaults to false if omitted.
externalReference string optional
An external reference used for cross-referencing between systems. This can be extracted via the TestSession and Result APIs.
qualityReview Boolean optional
Determines whether the test is scheduled as a quality review test. The test form’s status must be Quality Review or Live. Defaults to false if omitted.
unlockOverride object optional
Contains the information for override options. If omitted, the enforceTimes property’s 24-hour buffer is used, unless that is also false/omitted meaning that the specified times are used as standard.
unlockOverride/unlockForWholeDay Boolean
Determines whether to ignore the Start Time and End Time and allow the candidate to start the test at any time on the schedule day(s).
unlockOverride/daysInAdvanceToUnlock integer
Determines how many days ahead of the Start Date the test session becomes unlocked.
unlockOverride/daysAfterToLock integer
Determines how many days after the End Date the test session becomes locked.
forceRequireExamVersionDate Boolean optional
If true, the test window specified in the request is checked against the test form availability dates and times. The test cannot be scheduled if the specified test window falls outside of the test form availability dates and times. Defaults to false if omitted.
requiresCheckIn Boolean optional
isWholeScriptMarkingOn Boolean optional
pin string optional
The test session’s PIN. PIN codes must consist of six characters and contain a combination of numbers and uppercase letters. If omitted, a PIN code is randomly generated.
customReportId integer optional
The unique identifier of the custom report template assigned to the test session, if the Custom Reports site setting is enabled for reports to be automatically sent to candidates.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new test session’s details, the candidate’s unique keycode, and the test session’s PIN.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSchedule/1",
"errors": null,
"keycode": "QWHMNFX8",
"serverTimeZone": "GMT Standard Time",
"pin": "KVFRKT"
}Scheduling a test session with newly specified items
Send a request to the endpoint to schedule a candidate for a test session, with a newly specified group of items. Successful responses contain the candidate’s keycode and the test session’s PIN.
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. |
|
autoSyncCentreSubject |
header OPTIONAL |
{Boolean} |
If {Boolean} is true, associates candidates with the subject that contains the test you are scheduling. |
|
quickRegisterCandidate |
header OPTIONAL |
{Boolean} |
If {Boolean} is true, creates or updates the candidate specified in the request. See the Candidate property in the request schema for more details. |
Sample request
The following request contains the minimum required request body to schedule a candidate for a test session.
{
"Test": {
"id": 1
},
"Centre": {
"id": 1
},
"Candidate": {
"id": 1
},
"TestForm": {
"id": 1
},
"startDate": "04/12/2024",
"endDate": "04/12/2024",
"startTime": "1200",
"endTime": "1500",
"section": [
{
"items": [
{
"id": 1
}
]
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
Test object mandatory
Contains the test’s information.
Test/id integer
The test’s unique identifier.
Test/reference string
The test’s unique reference code.
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 mandatory
Contains the centre’s information.
Centre/id integer
The centre’s unique identifier.
Centre/reference string
The centre’s unique reference code.
Candidate object mandatory
Contains the candidate’s information. Only Candidate/id or Candidate/reference are required to schedule a candidate.
Candidate/firstName string
The candidate’s first name.
Candidate/middleName string
The candidate’s middle name.
Candidate/lastName string
The candidate’s last name.
Candidate/dateOfBirth string
The candidate’s date of birth in DD/MM/YYYY format.
Candidate/gender enumeration
The candidate’s gender. The available inputs are Male, Female, or Unspecified. Defaults to Unspecified if omitted.
Candidate/email string
The candidate’s email address.
Candidate/tel string
The candidate’s telephone number.
Candidate/uln integer
The candidate’s Unique Learner Number (ULN). A ULN consists of 10 numbers, and its visibility is determined by a Site Setting. For more information, read About Site Settings options.
Candidate/reasonableAdjustments Boolean
Whether the candidate has been granted additional time during tests. Defaults to false if omitted.
Candidate/reasonableAdjustmentPercentage integer
If Candidate/reasonableAdjustments is set to true, you can apply a custom reasonable adjustment value to the candidate.
Candidate/isExternal Boolean
If set to true, the candidate can only be edited via the Surpass API. This prevents synchronisation issues where candidates also exist on databases external to Surpass. Defaults to false if omitted.
Candidate/expiryDate string
The candidate’s expiry date, in YYYY/MM/DD format. Defaults to 10 years.
Candidate/id integer
The candidate’s unique identifier.
Candidate/reference string
The candidate’s unique reference code.
startDate string mandatory
The Start Date on which the test will be available for candidates, in DD/MM/YYYY format.
endDate string mandatory
The End Date is the last day on which the test can be sat, in DD/MM/YYYY format.
startTime string mandatory
The test session’s Start Time, in HHMM format.
endTime string mandatory
The test session’s End Time, in HHMM format.
reasonableAdjustments object optional
This object modifies the candidate’s test duration. Any candidate’s test duration can be modified, but candidates with Reasonable Adjustments (Candidate/reasonableAdjustments) enabled are granted additional time automatically.
The maximum extra time allowed to be given to candidates is determined at the test form level.
reasonableAdjustments/extraTimeMin integer
The length of extra time (in minutes) to give the candidate.
reasonableAdjustments/extraTimePercentage integer
The length of extra time (as a percentage of the test duration) to give the candidate.
reasonableAdjustments/reason string
Your reason for giving the candidate extra time.
markedExternally Boolean optional
If true, once completed the test bypasses marking in Surpass and instead moves to the Archived, warehoused state. Defaults to false if omitted.
allowMultipleOpenSessions Boolean optional
If true, Surpass logic is overridden to schedule the test even if the candidate is already scheduled for the test. Defaults to false if omitted.
requiresInvigilation Boolean optional
Determines whether the Requires Invigilation (requiresInvigilation) 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.
Defaults to the Requires Invigilation test level setting if omitted.
testTags array optional
Contains any tags to be added to the test session. Tags are displayed in the Invigilate screen. Tags cannot exceed 250 characters per tag.
TestForm object mandatory
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.
Marker object optional
Contains the allocated marker’s information.
Marker/id integer
The allocated marker’s unique (user) identifier.
Marker/reference string
The allocated marker’s unique (user) reference code.
Moderator object optional
Contains the allocated moderator’s information.
Moderator/id integer
The allocated moderator’s unique (user) identifier.
Moderator/reference string
The allocated moderator’s unique (user) reference code.
purchaseOrder string optional
Stores an external invoice number against the test session.
breakReasonableAdjustments object optional
This object modifies the candidate’s test break duration. Any candidate’s test break duration can be modified, but candidates with the Candidate/reasonableAdjustments property set to true are granted additional time automatically.
The maximum extra time allowed to be given to candidates is determined at the test form level.
breakReasonableAdjustments/extraTimeMin integer
The length of extra break time (in minutes) to give the candidate.
breakReasonableAdjustments/extraTimePercentage integer
The length of extra break time (as a percentage of the test duration) to give the candidate.
breakReasonableAdjustments/numberOfExtraBreaksPerSection integer
The number of extra breaks to give the candidate.
breakReasonableAdjustments/reason string
Your reason for giving the candidate extra break time.
subject object optional
Contains the information for the subject the test belongs to.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
unscheduledBreak object optional
Contains the information of any unscheduled breaks.
unscheduledBreak/extraTimeMin integer
The amount of time the candidate can use for breaks. If 0, the candidate has no break time. Defaults to 0 if omitted.
language enumeration optional
Determines the language used for the test driver’s interface and menus. This does not affect item content. Defaults to en if omitted.
The available languages and their codes are:
- Amharic (amh)
- Arabic – UAE (ar)
- Armenian – Eastern (arm)
- Azerbaijani (az)
- Bulgarian (bul)
- Chinese – Simplified (zh)
- Chinese – Traditional (zho)
- Croatian (hrv)
- Czech (ces)
- Danish (dan)
- Dutch (nl)
- English – UK (en)
- English – US (us)
- Estonian (est)
- Farsi (per)
- Finnish (fin)
- French (fr)
- French – Canadian (frc)
- Gaelic – Irish (gle)
- Gaelic – Scottish (ga)
- Galician (glg)
- German (ge)
- Greek (gre)
- Hebrew (heb)
- Hungarian (hun)
- Indonesian (ind)
- Italian (ita)
- Japanese (jpn)
- Khmer (khm)
- Korean (kor)
- Lao (lao)
- Latvian (lav)
- Lithuanian (lit)
- Maltese (mlt)
- Nepali (nep)
- Norwegian (no)
- Polish (pol)
- Portuguese (por)
- Portuguese – Brazilian (pob)
- Punjabi (iir)
- Romanian (ron)
- Russian (rus)
- Samoan (smo)
- Slovak (slk)
- Slovenian (slv)
- Somali (som)
- Spanish (sp)
- Thai (tha)
- Turkish (tur)
- Ukrainian (ukr)
- Vietnamese (vie)
- Welsh (we)
enforceTimes Boolean optional
Determines whether a 24-hour buffer is applied to tests, allowing candidates to enter their test session 24 hours either side of the scheduled start time. Defaults to false if omitted.
uploadResponses Boolean optional
Determines whether the test is to be delivered outside of Surpass. If true, the test session is set to the PaperResponseUpload state and its responses must be uploaded using the TestSession API or the Upload Responses button in the Invigilate screen. Defaults to false if omitted.
externalReference string optional
An external reference used for cross-referencing between systems. This can be extracted via the TestSession and Result APIs.
qualityReview Boolean optional
Determines whether the test is scheduled as a quality review test. The test form’s status must be Quality Review or Live. Defaults to false if omitted.
unlockOverride object optional
Contains the information for override options. If omitted, the enforceTimes property’s 24-hour buffer is used, unless that is also false/omitted meaning that the specified times are used as standard.
unlockOverride/unlockForWholeDay Boolean
Determines whether to ignore the Start Time and End Time and allow the candidate to start the test at any time on the schedule day(s).
unlockOverride/daysInAdvanceToUnlock integer
Determines how many days ahead of the Start Date the test session becomes unlocked.
unlockOverride/daysAfterToLock integer
Determines how many days after the End Date the test session becomes locked.
forceRequireExamVersionDate Boolean optional
If true, the test window specified in the request is checked against the test form availability dates and times. The test cannot be scheduled if the specified test window falls outside of the test form availability dates and times. Defaults to false if omitted.
requiresCheckIn Boolean optional
isWholeScriptMarkingOn Boolean optional
pin string optional
The test session’s PIN. PIN codes must consist of six characters and contain a combination of numbers and uppercase letters. If omitted, a PIN code is randomly generated.
section array mandatory
Contains the test form’s section’s information. The section must contain at least one item.
section/id integer
The section’s unique identifier.
section/reference string
The section’s unique reference code.
section/name string
The section’s name.
section/type enumeration
The type of section.
section/duration integer
The section’s duration.
section/description string
The section description.
section/randomiseItems Boolean
Determines whether the Randomise Items setting is enabled. If true, presents section items to candidates in a random order. Defaults to false if omitted.
section/passMarkType enumeration
Determines whether the pass mark type is Percentage or Score. If this property is omitted, the pass mark type is Score.
section/passMark integer
The section’s pass mark. This cannot exceed the total marks available for the items in the section. Defaults to 0 if omitted.
section/numberOfItemsToMark integer
Determines the Number of items to mark setting, which is the number of items you want to include in a candidate’s final mark. This can be between 1 and 5. Can be null or omitted if the number of items to mark does not need defining, in which case all items are required to be marked. Defaults to null if omitted.
section/unlockSection Boolean
Determines whether the Unlock Section setting is enabled. If true, unlocks SecureClient only for the section, allowing candidates to access apps (including the internet) and their local files. Defaults to false if omitted.
section/forwardOnlySection Boolean
Determines whether the Forward only section setting is enabled. If true, prevents candidates from returning to items that have already been answered. Candidates can only progress to the next item in the test. Defaults to false if omitted.
section/allowItemReview Boolean
Determines whether the Allow item review setting is enabled. If true, allows candidates in a forward-only section to view previously answered items in a read-only mode. Defaults to false if omitted.
section/itemsRequireResponse Boolean
Determines whether the Items require response setting is enabled. If true, prevents candidates from submitting a test if they have not attempted all items. If the test or section is forward only, candidates must attempt the item before they can move onto the next question. Defaults to false if omitted.
section/sectionBreak object
Contains any candidate break information for the section.
section/sectionBreak/enableBreak Boolean
Determines whether the Enable break after section setting is enabled. If true, adds a break after this section. Defaults to false if omitted.
section/sectionBreak/breakDuration integer
Determines the break duration in minutes.
section/sectionBreak/cancellable Boolean
Determines whether the Cancellable setting is enabled. If true, allows candidates to choose when to leave the break and return to the test. If false, candidates must wait for the break time to expire before returning to the test. Defaults to true if omitted.
section/items array
Contains the items in the section.
Items are given to candidates in the order specified in the request.
section/items/id integer
The item’s unique identifier.
section/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item. Defaults to true for questions or false for basic pages, if omitted.
section/items/group object
Contains any item groups’ information. You can group items so they appear on a single scrollable page when delivered to candidates.
section/items/group/name string
The item group’s name.
section/items/group/items array
Contains the items in the group’s information.
section/items/group/items/id integer
The item’s unique identifier.
section/items/group/items/nonScored Boolean
Determines whether the item is a scored (false) or non-scored (true) item. Defaults to true for questions or false for basic pages, if omitted.
customReportId integer optional
The unique identifier of the custom report template assigned to the test session, if the Custom Reports site setting is enabled for reports to be automatically sent to candidates.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new test session’s details, the candidate’s unique keycode, and the test session’s PIN.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TestSchedule/1",
"errors": null,
"keycode": "QWHMNFX8",
"serverTimeZone": "GMT Standard Time",
"pin": "KVFRKT"
}Deleting a scheduled test session
Send a request to the endpoint to delete a specific test session. 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/TestSchedule/{id} |
Deletes specified test session, where {id} is the test session’s unique identifier. |
|
keycode |
path OPTIONAL |
/api/v2/TestSchedule/{keycode} |
Deletes specified test session, where {keycode} is the candidate’s unique keycode. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the test session has been deleted by returning a null id.
{
"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. |
|
InvalidDateTimeRange |
10 |
The specified date and/or time range are invalid. |
|
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. |
|
TestNotFound |
17 |
The specified test could not be found. |
|
TheStartOrEndDatesAreNotWithinTheAvailableWindow |
26 |
The Start Date and/or End Date window falls outside of the test form availability dates. |
|
TheStartOrEndTimesAreNotWithinTheAvailableWindow |
27 |
The Start Time and/or End Time window falls outside of the test form availability times. |
|
TheCandidateIsAlreadyScheduledForTheExam |
29 |
The candidate is already scheduled for the test.
NOTE: The allowMultipleOpenSessions property can be passed in the request to allow the candidate to be scheduled for multiple test sessions.
|
|
TheStartAndEndDatesAreInvalid |
36 |
The Start Date and/or End Date are invalid. |
|
ReasonableAdjustmentsCantBeAdded |
37 |
Reasonable adjustments cannot be applied to the specified candidate. |
|
ReasonableAdjustmentsExtraTimePercentageLess |
38 |
The length of extra time (as a percentage of the test duration) given to the candidate is less than allowed. |
| ReasonableAdjustmentsExtraTimePercentageGreater
|
39 |
The length of extra time (as a percentage of the test duration) given to the candidate is more than allowed. |
| TheCandidateIsRetired |
48 |
The candidate has been retired and can therefore no longer be scheduled. |
| ScheduledTestIsLocked |
81 |
The test session is in Locked state. Only test session in Editable state can be deleted. |
| ScheduledTestHasMultipleTestSessions |
82 |
The specified test already has multiple scheduled test sessions. |
| NoScheduledTestsFound |
83 |
The specified test session could not be found. |
| BreakReasonableAdjustmentsExtraTimeLess |
143 |
The assigned reasonable adjustments time needs to be less. |
| BreakReasonableAdjustmentsExtraTimeGreater |
144 |
The assigned reasonable adjustments time needs to be greater. |
| BreakReasonableAdjustmentsNumberOfExtraBreakLess |
145 |
There are too many assigned reasonable adjustments breaks. |
| BreakReasonableAdjustmentsNumberOfExtraBreakGreater |
146 |
There are not enough assigned reasonable adjustments breaks. |
| BreakReasonableAdjustmentsReasonTextLengthLess |
147 |
The reason given for the extra reasonable adjustments break is too long. |
| BreakReasonableAdjustmentsReasonTextLengthGreater |
148 |
The reason given for the extra reasonable adjustments break is too short. |
| ItemNotFoundInProject |
168 |
Item specified in the request body of a request to the /OverrideItems endpoint is not in or shared with the specified test form’s subject. |
| GraderAssociationIsRequired |
180 |
The marker/moderator user associations are required. |
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: