SurpassLocal: 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
Read (ID) GET
Read (Reference) GET

Attributes for the Candidate Resource

Within the table below are all of the attributes included in the candidate resource. This includes the attribute name, data type, a description, and if it's a unique identifier.
Attribute Name Type Description Unique Identifier
id Int The unique identifier for a candidate X
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
href String The link to call the Candidate Resource. Unable to POST/PUT
extendedDemographics Blob Additional information about a candidate.
firstName String Candidate's first name
middleName String Candidate's middle name
lastName String Candidate's last name

GET Request and Return

The GET Candidate resource can be called directly by browsing to the URL. Below we have provided examples of JSON and XML responses that would be returned from the SurpassLocal API when requesting the GET method for the Candidate resource. It is important to remember that the returned 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)

Required Permissions

To successfully call the Candidate methods, the user validating the requests must exist within BTL's CMS system. If you require a password reminder or a new account to be created, send a request to the BTL Service Desk ( 

Feedback and Knowledge Base