Within the Surpass API there a several different types of results that are available at different stages of the assessment journey, each of these have been explained below:

Result - This is a submitted, marked and moderated test session that is available within the Test Administration screen in Surpass. Later this result is exported to our reporting interface where further rescoring and scale scoring changes can take place. The result resource will not return data that has been modified in reporting and will always return the latest information available within Test Administration.

AnalyticsResult -  This result is the latest version of a result in the reporting interface. If any changes have taken place in Reporting this resource will provide you with the the latest result data from Surpass.

HistoricalResult - This resource allows a system to consume all versions of results that have been manipulated within Reporting. It might be that a particular result is modified several times meaning it has different versions. The Historical result resource provides a method of auditing and consuming all versions of a particular result.

Each resource is mirrored where possible with additional properties being returned in AnalyticsResult and HistoricalResult. They contain all of the information regarding a single candidate’s completed exam session. This includes all of the low-level detail of the exam including item level response information.

AnalyticsResult Resource

Below we have listed the operations, http verbs and an example URL for the AnalyticsResult resource within the Surpass API. 

Operation	HTTP Verb	Example URL
Search and Filter	GET	https://...surpass.com/api/v2/AnalyticsResult/
Read (individual)	GET	https://...surpass.com/api/v2/AnalyticsResult/1 https://...surpass.com/api/v2/AnalyticsResult/A1B2C3D4

Properties for the AnalyticsResult Resource

In the table below we have provided all of the properties included in the AnalyticsResult Resource. This includes: the property name, type, if the attribute is available to filter when requesting the GET method and the available operators..

Property Name	Type	Description	Filter (GET)	Available Operators (GET)
historicalResults	resource (collection)	A collection of the previous states of the result due to affects from rescoring
historicalResults / id	int	The unique id of the previous state of the analytics result
historicalResults / href	string	The request URL to retrieve the historical result
changeDetails	object	an object containing details of any changes to the analytics result
changeDetails / type	enumeration	The latest change to affect the analytics result in rescoring. Available values: "Rescore", "ScaleScore"
changeDetails / dateApplied	dateTime	The date that the changes took place, this can be useful to poll to find any results that have had a change applied to them.	x	le, ge
changeDetails / user	resource (object)	The user that applied the change to the analytics result
changeDetails / user / id	int	The id of the user that applied the change to the analytics result
changeDetails / user / reference	string	The reference of the user that applied the change
changeDetails / user / href	string	The URL to request details of the user that applied the change to the analytics result
changeDetails / rescoringRules	resource (object)	Information on the exact rescoring rules that have been applied to the analytics result since it was warehoused.
changeDetails / rescoringRules / id	int	The id of the rescoring rules resource
changeDetails / rescoringRules / href	string	The URL to request the rescoring rules that have been applied to a particular analytics result.
id	int	The unique id for this result.
reference	string	The reference for this resource is the keycode assigned to the test session which is used by the candidate to start the test.
href	string	The URL to request this specific resource.
subject	resource	The subject the test belongs to. ID and Reference can be used when filtering.	x	eq
test	resource	The test that was delivered. ID and Reference can be used when filtering.	test	that
testForm	resource	The test form that was delivered. ID and Reference can be used when filtering.	x	eq
centre	resource	The centre the test was delivered at. ID and Reference can be used when filtering.	x	eq
candidate	resource	The candidate that took the test. ID and Reference can be used when filtering.	x	eq
keycode	string	The unique identifier for the test session and used by the candidate to start the test.	x	eq
mark	int	The mark achieved for the entire test.
availableMarks	int	The total number of marks available for a test.
passMark	int	The mark for the lowest grade boundary set on the test.
passMarkType	enumeration	The pass mark type that was selected in Test Creation. Available values: "Percentage" or "Mark".
percentageMark	int	The mark achieved by a candidate displayed as a percentage.
passPercentage	int	The percentage required to achieve the lowest grade boundary set on the test.
pass	boolean	Used to identify if the candidate has passed all sections, learning outcomes and achieved the pass marks stated above.
grade	string	The grade that the candidate achieved for this result.
startedDate	date/time	The date/time the test was started.	x	le, ge
submittedDate	date/time	The date/time the test was submitted.	x	le, ge
warehousedDate	date/time	The date/time the test was warehoused in Test Administration. This is the date the test was released to results/audit after the test was marked and moderated	x	le, ge
resultReleased	boolean	Identifies if the test was moderated in Surpass.
resultSampled	boolean	Identifies if the test was released as a group in moderation.
scaleScore	int	The scale score the candidate received for this result.
durationMode	string	The time settings for the test, will read 'Untimed', 'Timed' or 'Timed Sections'.
isManuallySubmittedInLocal	boolean	Identifies if the test was manually submitted by SurpassLocal.
scaleScoreMapping	resource	A link to the full scale score mapping that was used for this test.
learningOutcomeThreshold	int	The sum of marks assigned to a learning outcomes required before Surpass marking logic incorporates learning outcome boundaries into the result of a test. It may be that a Learning outcome only has 1 mark assigned and therefore inappropriate to grade the candidate on this learning outcome until more marks are assigned (threshold value).
learningOutcomeBoundariesApplied	boolean	Learning outcome boundaries have been applied to this result. They will only affect the result if the marks exceeds the threshold value.
sections	collection	A collection of sections contained within the test
sections / name	string	The section name.
sections / mark	int	The mark achieved within the section.
sections / percentageMark	int	The mark a candidate achieved for a section represented as a percentage.
sections / availableMarks	int	Total marks available within the section.
sections / pass	boolean	Boolean value identifing if the candidate has passed that section.
sections / passMark	int	The pass mark required to pass the section.
sections / passPercentage	int	The pass mark required to pass the section represented as a percentage.
sections / passMarkType	enumeration	The pass mark type that was selected in Test Creation. Values: "Percentage" and "Mark".
sections / viewingTime	int	The time spent on this particular section of the test.
sections / isSurveySection	boolean	This indicates whether the section is set up as a survey section which contains non-scored question items for candidates to record their opinions (such as their feedback on the test experience).
sections / items	collection	a collection of items contained within a section.
sections / items / name	string	The name of an item delivered within a test.
sections / items / version	int	The version number of the delivered item.
sections / items / mark	int	The mark achieved by a candidate for that particular item between 0-1.
sections / items / awardedMark	int	The awarded mark for a particular item.
sections / items / availableMarks	int	The total number of available marks for an item.
sections / items / viewingTime	int	The time spent viewing an item.
sections / items / learningOutcome	string	The learning outcome assigned to a particular item delivered within the test.
sections / items / unit	string	The unit assigned to a particular item delivered within the test.
sections / items / surpassReference	string	The unique Surpass reference for the delivered item.
sections / items / nonScored	boolean	Boolean value that identifies if the item was scored or non scored.
sections / items / type	enumeration	The type of item delivered. Available values: "Question" , "Survey"
sections / items / group	collection	The id and name of the group of items, where applicable.
sections / items / candidateResponse	XML	The raw XML used to calculate a candidates response.
sections / items / itemComment	string	Any item comments provided by the candidate during delivery.
sections / items / itemResponse	resource	The response for an Item in a user friendly model. Only MCQ, MRQ and EitherOr supported. This will provide the URL to retrieve this from the Item Response resource.
learningOutcomes	collection	A collection of learning outcomes that have been assigned to items within the test.
learningOutcomes / name	string	The name of the learning outcome assigned to the test
learningOutcomes / pass	boolean	This flag identifies if the candidate has passed this learning outcome
learningOutcomes / mark	int	The mark achieved for all items that have this learning outcome assigned.
learningOutcomes / totalMark	int	The total number of marks for all items that have this learning outcome assigned.
learningOutcomes / percentageMark	int	The mark achieved for all items that have this learning outcome assigned in percentage format.
learningOutcomes / passPercentage	int	The pass percentage required for this learning outcome
learningOutcomes / thresholdExceeded	boolean	This flag identifies if the number of item marks has exceeded the threshold value and therefore counts towards the final result of the test
learningOutcomes / defaultPassMarkApplied	boolean	This flag identifies if this learning outcomes pass mark uses the default value, if this is false then the test creator defined a custom learning outcome boundary pass mark.
learningOutcomeBoundaries	collection	A collection of the learning outcome boundaries setup by the test creator.
learningOutcomeBoundaries / isDefault	boolean	This flag identifies if the learning outcome boundary was setup to use the default pass mark.
learningOutcomeBoundaries / text	string	The Learning outcome boundary text that was entered in test creation. This value might not match the value on the item if there was a mistake in the authoring / test creation process and therefore not affect the result.
learningOutcomeBoundaries / passPercentage	int	The pass percentage for this leanring outcome boundary.

Additional Notes 

·       When filtering analytics results you can use the same attribute twice for date fields such as “warehousedDate” this allows you to search between two dates. The format for this request would be as follows:

https://...surpass.com/api/v2/AnalyticsResult?$filter=warehousedDate ge 08/06/2015T00:00:00 and warehousedDate le 09/06/2015T00:00:00
                                                                                                       

·      The AnalyticsResult resource has been extended to provide a user friendly item response model for MCQ, MRQ and Either or question types. This can be requested by calling the Item Response Resource directly or within the AnalyticsResult response by passing the query string parameter 'showItemResponses=true' to the GET/{id}, GET{Keycode} method. Below we have provided the request URL for the methods of extracting item responses:

https://...surpass.com/api/v2/AnalyticsResult/{Keycode/ID}?showItemResponses=true - returns full analyticsResult request with the item response model
https://...surpass.comapi/v2/AnalyticsResult/{Keycode/ID}/ItemResponse/{Item Authoring ID} - returns the response for one item 
https://...surpass.comapi/v2/AnalyticsResult/{Keycode/ID}/ItemResponse/ - returns a list of the item response URLs contained within a analytcisResult 

GET AnalyticsResult Request and Return

The AnalyticsResult Resource can be called directly by browsing to the URL. Any parameters such as markedExternally, $filter, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the Result resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response. This is detailed in the page "Understanding the Surpass API".

Example GET request & response (JSON)

Example GET request & response (XML)

 

Filtering AnalyticsResults on Resource objects

The GET AnalyticsResult method allows you to filter on resource objects contained within the AnalyticResult Resource. Subjects, centres, tests, test forms and candidates for that exam session are returned within a standard result response. When filtering on these attributes, you need to additionally specify what attribute we are searching on within that resource, so this is built differently to other attributes contained within the Result Resource. Below we have provided some examples of how these requests are built:

https://...surpass.com/api/v2/AnalyticsResult?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’

https://...surpass.com/api/v2/AnalyticsResult?$filter=subject/id eq 21 and centre/id eq 25

Item Response Resource

Candidates responses are returned as part of the AnalyticsResult response in raw XML format ("candidateResponse" property) or via a user friendly model accessible via a separate resource. Further information regarding the Item Response resource can be found by selecting the following link:  

Item Response Resource

Required Permissions

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