CandidateReview API

A candidate review session allows candidates to re-enter their tests to review the items and their responses. In Surpass, the Candidate Review screen is where candidate review sessions are scheduled for particular candidates on a specific date and time.

The CandidateReview API resource is used to schedule candidate review sessions.

TIP: Scheduled candidate review sessions can be launched directly from a URL. Read the ‘Launching candidate review sessions from a URL’ section in ‘Scheduling a candidate review session’ below for more information.

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

Import this API into your Postman Workspace

Scheduling a candidate review session

post /api/v2/CandidateReview

Send a request to the endpoint to schedule a candidate review session. Successful responses contain the candidate’s unique keycode and the passcode required to access the scheduled candidate review session.

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 OPTIONAL	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.

Request body schema

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

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.

startDate string mandatory

The Start Date on which the candidate review session will be available, in DD/MM/YYYY format.

endDate string mandatory

The End Date is the last day on which the candidate review session can be accessed, in DD/MM/YYYY format.

startTime string optional

The candidate review session’s Start Time, in HHMM format. Defaults to 0000 if omitted.

endTime string optional

The candidate review session’s End Time, in HHMM format. Defaults to 2359 if omitted.

keycodes array mandatory

Contains the candidate’s keycode.

NOTE: Only one keycode can be included per request.

showViewFeedbackButton Boolean optional

Determines whether the Show View Feedback Button test feedback setting is enabled. If true, allows candidates to view Correct/Incorrect/General feedback left on items during the summary feedback. Review Answers must also be enabled for a candidate to access the feedback button. Defaults to false if omitted.

displayFeedbackByLearningOutcome Boolean optional

Determines whether the Display Feedback by Learning Outcome test feedback setting is enabled. If true, displays how candidates scored on items with shared tag values. Defaults to false if omitted.

enableMarkerCommentsAndAnnotations Boolean optional

Determines whether the Enable marker comments & annotations setting is enabled. If true, allows candidates to view any comments or annotations added to responses by markers or moderators. Defaults to false if omitted.

Name	Parameter	Input	Description
keycode	query MANDATORY	`keycode={keycode}`	The candidate’s unique keycode.
passcode	query MANDATORY	`passcode={passcode}`	The scheduled candidate review session’s passcode.
language	query OPTIONAL	`language={language}`	Determines the language used for the test driver’s interface and menus. This does not affect item content. Defaults to `en` if omitted. Refer to the TestSchedule API‘s request body schema for a full list of available languages.
backgroundColour	query OPTIONAL	`backgroundColour={backgroundColour}`	The hex colour code for the test driver’s background, in URL-encoded format, for example `#0000F` is encoded as `%230000ff`. NOTE: If passing `backgroundColour` in your URL, `textColour` must also be included.
textColour	query OPTIONAL	`textColour={textColour}`	The hex colour code for the test driver’s text, in URL-encoded format, for example `#0000F` is encoded as `%230000ff`. NOTE: If passing `backgroundColour` in your URL, `textColour` must also be included.

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.
NoSubjectsAssociated	12	There are no subjects associated with what is defined in the request.
InaccessibleCandidate	13	The candidate defined in the request cannot be accessed.
KeycodesLimitExceeded	15	The number of keycodes exceeds the max allowed limit of 1.
InvalidId	16	The ID number used in the request is invalid.
InvalidODataOperation	19	There is an issue with the query parameters.
NotFoundInWarehouse	194	The script must be in Warehoused state.

CandidateReview API

In This Article

Scheduling a candidate review session

Parameters

Sample request

Request body schema

Sample response

Response body schema

Parameters

Error Codes

About the site