Candidate Resource

Within Surpass candidates are the people that take exams within the system. They do not interact with the main Surpass user interface and only see the Surpass exam delivery engine in the end-to-end exam delivery process (Web Delivery, SecureClient, Surpass Tablet App). Information can be stored against the candidate within the system and associations are made to centres and subjects. Candidates will only be eligible to take exams at centres and subjects they are associated to.

Candidate Resource

Below we have listed the operations HTTP verbs and an example URL for the Candidate resource within the Surpass API.
Operation HTTP Verb Example URL
List GET
Filter GET$filter=contains(lastname, 'smith')
Read (Individual) POST By ID:

By Reference:
Create POST
Update PUT

Attributes for the Candidate Resource

Within the table below we have provided all of the attributes included in the candidate resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method, if the attribute is available to filter when requesting the GET method, and if the attribute is mandatory when creating a candidate. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.
Attribute Name Type Description Order (GET) Filter (GET) Available Operators (GET) Unique Identifier Mandatory for Create (POST)
id Int The unique identifier for a candidate X N/A
reference String The unique candidate reference, usually used to map external interfaces. The API request does not support the ability to update this value. X eq, contains X
href String The link to call the Candidate Resource. Unable to POST/PUT N/A
firstName String Candidate's first name X X eq, contains X
middleName String Candidate's middle name X X eq, contains
lastName String Candidate's last name X X eq, contains X
dateOfBirth Date Candidate's date of birth X eq X
gender string Candidate's gender, can be set to 'Unspecified', 'Male' or 'Female'. X eq
email String Email address of the candidate X eq, contains
tel String The telephone number of the candidate X eq, contains
reasonableAdjustments Boolean If this is set to true the candidate will receive the 'standard' additional time set on all tests within Test Creation. X eq
retired Boolean If this is set to true the candidate will not be available for test scheduling. Candidates can be reactivated. X eq
isExternal Boolean If this is set to true the candidate will not be available for editing in the UI only via the Surpass API.
uln Int The candidates unique learner number. This can be enabled/disabled in Site Settings of Surpass as it does not apply for all Surpass customers. This must be unique, 10 digits and not start with 0.
centres Resource The centres a candidate is associated with. Candidates will be eligible to take tests at this centre. X eq X
subjects Resource The subjects a candidate is associated with. Candidates will be eligible to take any test within the associated subjects. X eq
expiryDate dateTime The date that a candidate will expire and therefore not be able to take tests until this has been updated. If this is omitted the value will default to 10 years in the future.

Additional Notes
  • ID or reference can be used in the query string when sending a GET request for this resource. 
  •  If date of birth is omitted in the POST request, this will be set to 01/01/1900 and will be displayed to the candidate at the candidate details screen when beginning a test. If using this method, it is advisable to create a Test Profile which excludes the date of birth field from this screen to avoid concerning candidates who discover their date of birth is incorrect. 

GET Request and Return

The GET Candidate resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the url that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the Candidate resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page Using the Surpass API.

Example GET request & response (JSON)
Example GET request & response (XML)

Filtering Candidates on Resource Objects

The GET Candidate method allows you to filter on resource objects contained within the candidate resource. Within a standard candidate response all associated subjects and centres are returned. Due to these being a separate object and that there is functionality that lets users state multiple centres in the request, this query is built slightly differently. Please see the below example to see how this would be achieved. Currently we only support “OR” if multiple centres/subjects are being stated; candidates returned will be associated to at least one of the centres specified.

api/v2/Candidate?$filter=centres/any(c: c/reference eq 'centre ref1' or c/reference eq 'centre ref2')
api/v2/Candidate?$filter=subject/any(s: s/reference eq 'subject ref1' or s/reference eq 'subject ref2')

The first request will return all candidates that have an association to the centre with the reference “centre ref1” or with the reference “centre ref2”. They do not have to be associated to both.

api/v2/Candidate/?$filter=centres/any(c: c/id eq 31 or c/id eq 32)
api/v2/Candidate/?$filter=subjects/any(s: s/id eq 31 or s/id eq 32)

The first request will return all candidates that have an association to the centre with ID 31 or the centre with ID 32. They do not have to be associated to both.

POST Request and Return

The POST Candidate method requires the attributes listed above to be submitted as part of the body of the request. This can be submitted in either JSON or XML format, the content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request for both formats can be found below.

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.

Example POST request & response (JSON)
Example POST request & response (XML)

PUT Request and Return

PUT Requests should reference the ID or Reference within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. All properties are optional within the PUT request so any omitted proprieties will be unchanged, however it is important to point out that if centres or subjects are sent into the request this is an explicit list of associations and you are not adding additional centre and subject associations to the candidate. The Authorization header will also be required in the request for it to be successful.

The body of the request should be formed in the same way as the POST request and the response also returns the same information. An example of this can be found in the “POST Request and Return” section above. The only differences between the POST and PUT requests is that the reference is required as part of the URL and all fields are optional here.

It is possible to create a candidate entry in Surpass using a PUT request using the additional header 'postlfNew', this could be used to cut down the amount of communication required with the Surpass API. For further information on this, please see the 'PUT Requests and Responses' section of the 'Using the Surpass API' article.

Required Permissions

To successfully call the Candidate methods, the user specified in the header of the request must have the 'Manage Candidates' permission in Surpass and be associated to the relevant centre and subject that is contained within the request.

Feedback and Knowledge Base