SurpassLocal - CandidateInformation Resource

The CandidateInformation resource can be used to send additional candidate information to the SurpassLocal API in order to populate the customisable score report with this.

CandidateInformation Resource

Below we have listed the operations, http verbs and an example URL for the CandidateInformation resource within the SurpassLocal API.



Example URL

Update by id


Update by keycode


Attributes for the CandidateInformation Resource

Within the table below we have provided all of the attributes included in the test schedule resource. This includes the attribute name, data type and if the attribute is mandatory when sending a POST request. Remember that if an attribute is not mandatory, it can be omitted from the body of the POST request. 

Attribute Name



Unique Identifier







This is the unique keycode generated in Surpass. It appears in the invigilate screen




Could be anything and no longer than 50 characters and not empty.




Could be anything but not empty.


PUT Request and Return

PUT Requests should reference the ID or keycode 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. Only the field you want to be updated needs to be included within the request all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.

Example PUT request & response (JSON)

Example PUT request & response (XML)

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 SurpassLocal API can be found here.

Required Permissions

To successfully call the methods in the Surpass Local TestSession Resource, 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