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

post /api/v2/TestSchedule

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.

NOTE: If a candidate is scheduled at the same centre, for the same test, and on the same day as other candidate(s), the PIN generated will be the same as theirs. This differs to the Surpass UI behaviour, where a new PIN is generated for each test session scheduled from the Schedule screen regardless.

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"
}

EXAMPLE: In this sample request, Candidate 1 is scheduled to sit Test 1 from Centre 1 on 11/02/2023 at 12:00 until 15:00.

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.

TIP: If the quickRegisterCandidate header parameter is included as true in the request, a new candidate is created. Only the candidate’s first name, last name, and date of birth are required. To update the details of an existing candidate, include that candidate’s ID or reference as part of this object. This prevents the need for sending requests to both the Candidate and TestSchedule APIs.

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.

IMPORTANT: The candidate’s date of birth is set to 01/01/1900 if omitted. This may appear to the candidate at the beginning of a test, unless excluded from the test profile. For more information, read ‘Candidate Details’ in About test profile settings.

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.

NOTE: Surpass never contacts candidates via email.

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/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.

IMPORTANT: If the Test Scheduling Over Multiple Days site setting is disabled, the start date and end date must not be longer than one day. For more information, read ‘About Test settings’ in About Site Settings options.

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.

NOTE: If the test-level Enable strict control for Reasonable Adjustments (strictControlReasonableAdjustments) setting is enabled, only users with the Add extra time to tests with strict control for reasonable adjustments permission can give extra time to candidates with reasonable adjustments enabled.

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.

NOTE: If the test level setting is true, this property cannot be passed as false.

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.

IMPORTANT: If the centre is set to Randomise Test Forms, this property must be omitted. If the centre is set to Select Test Forms, this property is mandatory. In addition, if the test form setting Exclude from Random Test Form Selection (excludeFromRandomTestFormSelection) is enabled, this property is mandatory.

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.

IMPORTANT: The User Type – Marker (userAssociations/enableMarker) test setting must also be enabled. If the Restrict User Access (userAssociations/requireMarker) test setting is enabled, this property is mandatory.

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.

IMPORTANT: The User Type – Moderator (userAssociations/enableModerator) test setting must also be enabled. If the Restrict User Access (userAssociations/requireModerator) test setting is enabled, this property is mandatory.

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.

IMPORTANT: If the Purchase Order for Scheduling site setting is enabled, this property is mandatory. For more information, read ‘About Test settings’ in About Site Settings options.

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.

TIP: This should be used to distinguish the test/test form if there are tests/test forms across subjects with the same reference code.

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)
Burmese (mya)
Chinese – Simplified (zh)
Chinese – Traditional (zho)
Croatian (hrv)
Czech (ces)
Danish (dan)
Dutch (nl)
English – UK (en)
English – US (us)
Estonian (est)
Farsi (per)
Filipino – Tagalog (tgl)
Finnish (fin)
French (fr)
French – Belgian (frb)
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)
Mongolian (mon)
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)
Spanish – Latin American (lac)
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.

IMPORTANT: If the Strict Control of Test Time site setting is enabled, this property is mandatory. For more information, read ‘About Test settings’ in About Site Settings options.

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

NOTE: This is a retired property and should therefore not be used.

isWholeScriptMarkingOn Boolean optional

NOTE: This is a retired property and should therefore not be used.

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.

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

delete /api/v2/TestSchedule/{id}

Send a request to the endpoint to delete a specific test session. No request body is required.

IMPORTANT: Only test sessions in Editable state can be deleted. Test sessions are in Editable state until the test has been downloaded; this is at states 1 (ScheduledButNotCreated) and 2 (ScheduledButNotDownloaded).

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.
GraderAssociationIsRequired	180	The marker/moderator user associations are required.

TestSchedule API

In This Article

Scheduling a test session

Parameters

Sample request

Request body schema

Sample response

Deleting a scheduled test session

Parameters

Sample response

Error Codes

Further reading

About the site