Calling the GetDetailedResults 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 GetDetailedResults web method in the Surpass API returns a separate url for each exam that is returned from the parameters you have specified in the request. The URL returned is the web address you will need to call to run the GetDetailedResult method to find out the detailed item level information regarding that result.

GetDetailedResults 


GET api/v1/TestResults/GetDetailedResults?testReference={testReference}&centreReference={centreReference}&subjectReference={subjectReference}&startRangeDateTime={startRangeDateTime}&endRangeDateTime={endRangeDateTime}&pageNumber={pageNumber}

Input Parameters


The input parameters that are required for the GetDetailedResults web method are as follows:
Input ParameterTypeDescription
testReference Type: String, max length: 50, mandatory The test reference of the exams you would like the web method to return. This is specified in the Test Creation section of Surpass Editions.
centreReference Type: String, optional The centre reference of the exams you would like the web method to return. This is specified in the Setup section of Surpass Editions.
subjectReference Type: String, optional The subject reference of the exams you would like the web method to return. This is specified in the Setup section of Surpass Editions.
startRangeDateTime Type: DateTime, mandatory The web method will only return results on or after this date/time.
endRangeDateTime Type: DateTime, mandatory The web method will only return results before this date/time.
pageNumber Type: int, mandatory Results are returned in pages to limit the number of responses returned, this value denotes the page number. When calling this for the first time the user should send ‘1’, the number of pages will be included as part of the response’s header.

Request


The GetDetailedResults web method can be called directly by browsing to the url, the above parameters will need to form part of the url that is sent.

An example of this call is as follows:

https://[YourSurpassEnvironment]/api/v1/TestResults/GetDetailedResults?testReference=BTL Demo Test&centreReference=BTL Centre 123&subjectReference=BTLDemo&startRangeDateTime=2013-12-02T00:00:00&endRangeDateTime=2013-12-17T00:00:00&pageNumber=1
  • 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”
  • To remove optional parameters such as centreReference and subjectReference the parameter should be left out of the URL, an example of this call without the optional nodes has been provided below:
https://[YourSurpassEnvironment]/api/v1/TestResults/GetDetailedResults?testReference=BTL Demo Test&startRangeDateTime=2013-12-02T00:00:00&endRangeDateTime=2013-12-17T00:00:00&pageNumber=1

Required Permissions


To successfully call GetDetailedResults the user specified in the header of the request must have the 'View Results' permission in Surpass and be associated to the relevant centre and subject contained within the request.

Return

The response from the GetDetailedResults method will detail all exams that successfully match the input parameters requested by the user. Information contained within the GetDetailedResults response will provide the user with the URL to call the GetDetailedResult method.

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 response has been included below:

[

"https://[YourSurpassEnvironment]/api/v1/TestResults/GetDetailedResult?keycode=8FHUR9D1",

https://[YourSurpassEnvironment]/api/v1/TestResults/GetDetailedResult?keycode=PWUBSAD1

]

Next Article 

Feedback and Knowledge Base