Calling the PutCandidate Method in the Surpass Web API

Note: Version 2 of the Surpass API is now available. For any customers not already using API v1, please refer to the API v2 Developer Portal.

The PutCandidate web method in the Surpass API allows a user or external system to create or update a candidate in the Surpass system.

PutCandidate


PUT  api/v1/CandidateRegistration/PutCandidate?

Input Parameters


The input parameters that are required for the PutCandidate web method are as follows:
Input ParameterTypeDescription
DateOfBirth Type: DateTime, mandatory The date of birth of the candidate you are adding to the system.
SpecialRequirements Type: bool, optional The Special requirements option indicates that a candidate requires extra time for their exam. This time will be automatically added to the assessment; however this can be overridden either at the point of scheduling or in the invigilation screen in Test Administration.
SubjectAssociation Type: SubjectModel[], mandatory, {reference: string, max length:30, mandatory} Within the subject model you must add the references of all of the subjects the candidate is associated with. The candidate will only be able to take exams from these subjects.
CentreAssociation Type: CentreModel[], mandatory, {reference: string, max length:30, mandatory} Within the candidate model you must add the references of all of the centres the candidate is associated with. The candidate will only be able to take exams at the centres they are associated with.
Forename Type: String, max length:50, mandatory The forename of the candidate you are adding to the system.
Surname Type: String, max length:50 mandatory The surname of the candidate you are adding to the system.
Reference Type: String, max length:50 mandatory The unique candidate reference you would like to assign the candidate. This is also the unique identifier, so if a candidate already exists on the system with the reference submitted in the parameters the candidate will be updated rather than added.

Request


The PutCandidate web method requires the parameters to be submitted as part of the body of the request. This can be submitted in JSON or XML format, the content-type used will need to be submitted as part of the header of the request. This call should be sent as a PUT REST request to the following address: 

https://[YourSurpassEnvironment]api/v1/CandidateRegistration/PutCandidate?

  • To submit a request without the optional parameters the request needs to be submitted with the parameter completely removed from the body of the request.
  • When performing an update using the PutCandidate web method, all subjects and centres associated to the candidate in the PutCandidate request will overwrite any existing associations.
  • The user requesting this web method must have the permission to create candidates in the system.
  • The DateTime value is any able to parse by C#. This also must be kept inside double quotes. An example datetime is as follows: "2013-12-18T07:23:26.550375+00:00
An example of the request using both formats can be found by selecting the below links:  

JSON Request
XML Request

Required Permissions


To successfully call PutCandidate 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.

Return


Depending on how the request was submitted the response will be in either JSON or XML format, if the response is successful you will be presented with the candidates reference and a “success:true” message.

If the call was unsuccessful then you will receive an error message, all error messages available in the Surpass API can be found here.

An example of the response in both formats can be found using the below links:  

JSON response 
XML Response

Next Article

Feedback and Knowledge Base