Calling the GetReport 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 GetReport web method in the Surpass API returns all information on the report that was passed into the parameters of the call. Reports available can be found by calling the GetAvailableReports method. There is also means to generate a Raw Data Extract from the Item Performance Analysis. 

GetReport


GET api/v1/Analytics/GetReport?

Input Parameters


The input parameters that are required for the GetReport web method are as follows:
Input ParameterTypeDescription
Name Type: String, optional The name of the report you are trying to retrieve, this information is provided when you call the GetAvailableReports web method.
ID Type: int, mandatory The ID of the report you are trying to retrieve, this information is provided when you call the GetAvailableReports web method.
ParametersCollection Type: Dictionary<string object>, optional The parameters of the report you are requesting. This includes information such as the centres and subjects you want to search for and the date range of the report.

Request

The GetReport web method requires the parameters to be submitted as part of the body of the request. This call should be sent as a POST REST request to the following address: 

https://[YourSurpassEnvironment]api/v1/Analytics/GetReport?

  • The user requesting this web method must have the permission to view reports in Surpass.
  • ParametersCollection: All required subjects, centres, tests, test forms, folders and items in the parameter collection require the relevant Surpass reference or ID.
  • ParametersCollection: COLLECTION – This allows for multiple values to be contained in an array. To specify multiple values the collection must be used in the following format:

    ["Sample 1", "Sample 2", "Sample 3"]
  • ParametersCollection: DATETIME – The DATETIME values can be any that could be parsed by C#. The DATETIME value also must be kept inside double quotes. An example DATETIME is as follows: "2013-12-18T07:23:26.550375+00:00"
  • ParametersCollection: STRING – Single value that must be contained within double quotes.
  • ParametersCollection: When defining the status for the distractor analysis report you must provide the ID. Draft = 0, Ready for Review = 1, Reviewed = 2, Live = 3, Withdrawn = 4.
  • Folder ID's required for the "Item Production Report" can be found by calling the "Authoring Folders Report".

An example of the request using both formats can be found by selecting the below links:  

Required Permissions


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

Return

The response from the GetReport web method will provide all information on the report that was passed into the parameters of the call. The response from this call will be in XML format.

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 'Test Performance Report' response can be found by selecting the below link:

XML Response

Next Article 

Feedback and Knowledge Base