HistoricalResult Resource
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 tools to extract 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.
| Operation | HTTP Verb | Example URL |
|---|---|---|
| Search and Filter | GET | https://...surpass.com/api/v2/HistoricalResult/ |
| Read (individual) | GET | https://...surpass.com/api/v2/HistoricalResult/1 https://...surpass.com/api/v2/HistoricalResult/A1B2C3D4 |
Properties for the HistoricalResult Resource
In the table below we have provided all of the properties included in the HistoricalResult Resource. This includes: the property name, type, if the property is available to filter when requesting the GET method and the available operators.
| Property Name | Type | Description | Filter (GET) |
Available Operators (GET) |
|---|---|---|---|---|
| isLatest | boolean | This flag identifies if the historical result is the latest and therefore the same as the analytic result. | ||
| adjustedGrade | string | The grade assigned to the historical result after a rescoring event. | ||
| changeDetails | object | An object containing details of any changes to the historical result | ||
| changeDetails / type | enumeration | The latest change to affect the historical 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 historical result | ||
| changeDetails / user / id | int | The id of the user that applied the change to the historical 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 historical result | ||
| changeDetails / rescoringRules | resource (object) |
Information on the exact rescoring rules that have been applied to the historical 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 historical result. | ||
| id | int | The unique id for this result. | ||
| 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. | ||
| 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. | ||
| scaleScore | int | The scale score the candidate received for this result. | ||
| 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. |
- When filtering historical 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/HistoricalResult?$filter=warehousedDate ge 08/06/2015T00:00:00 and warehousedDate le 09/06/2015T00:00:00
GET HistoricalResult Request and Return
The HistoricalResult 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 HistoricalResult 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 HistoricalResults on Resource objects
The GET HistoricalResult method allows you to filter on resource objects contained within the HistoricalResult 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/HistoricalResult?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’
https://...surpass.com/api/v2/HistoricalResult?$filter=subject/id eq 21 and centre/id eq 25
Item Response Resource
Candidates responses are returned as part of the HistoricalResult 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 HistoricalResult methods, the user specified in the header of the request must have the 'View Reporting' permission in Surpass and be associated to the relevant centre and subject contained within the request.