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.
|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.|
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.
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.
An example of the response in both formats can be found using the below links:JSON response