Calling the GetCandidates 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 GetCandidates web method in the Surpass API returns all candidates that match the parameters that were passed into the call. The candidate information returned includes date of birth, if the candidate has special requirements, the centres and subjects they are associated with, their first name, last name and candidate reference. This is presented in the exact same format as the PutCandidate web method.


GET api/v1/CandidateRegistration/GetCandidates?pageNumber={pageNumber}&dateOfBirth={dateOfBirth}&specialRequirements={specialRequirements}&subjectAssociation={subjectAssociation}&centreAssociation={centreAssociation}&forename={forename}&surname={surname}&reference={reference}

Input Parameters

The input parameters that are required for the GetCandidates web method are as follows:

Input ParameterTypeDescription
pageNumber Type: int, optional  Results are returned in pages to limit the number of responses returned, this value denotes the page number. This is an optional parameter, if this is left blank it will default to 1. The number of pages will be included as part of the response’s header.
dateOfBirth Type: DateTime, optional The date of birth of the candidate/s you would like the web method to return. This is specified in the Setup section of Surpass Editions.
specialRequirements Type: Boolean, optional If the candidate/s you would like the web method to return has special requirements assigned to them. This parameter expects either true or false.
subjectAssociation Type: Comma separated String, optional  The subject references associated to the candidate/s you would like the web method to return. This allows multiple values.
centreAssociation Type: Comma separated String, optional   The centre references associated to the candidate/s you would like the web method to return. This allows multiple values.
forename Type: String, optional  The first name of the candidate/s you would like the web method to return.
surname Type: String, optional The last name of the candidate/s you would like the web method to return.
reference Type: String, optional  The candidate reference of the candidate you would like the web method to return.
The GetDetailedResult web method can be called directly by browsing to the url, the parameters used will need to form part of the url that is sent.

An example of the request for this web method is as follows:

  • There must be at least one parameter stated. This does not include ‘pageNumber’.
  • The total page number is returned as part of the header of the response.
  • If the page number has not been stated this will default to 1.
  • When stating multiple centre/subject associations in the request, candidates must match with at least one association to be returned.
  • 20 candidates are provided per page.

Required Permissions

To successfully call GetCandidates 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. Only candidates at user associated centres and subjects will be returned.


Depending on how the request was submitted the response will be returned in either JSON or XML format, the response will return detailed item level information of the result that was requested as part of the input parameters.

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

Feedback and Knowledge Base