Result Resource

Within the Surpass API, a result is all of the information regarding a single candidate’s completed exam session prior to any reporting changes. This includes all of the low-level detail of the exam providing the raw item level response information within the response. 
   
Result Resource

Below we have listed the operations, HTTP verbs and an example URL for the result resource within the Surpass API.  
Operation HTTP Verb Example URL
Search and Filter GET https://...surpass.com/api/v2/result/
Read (individual) GET https://...surpass.com/api/v2/result/1
https://...surpass.com/api/v2/result/A1B2C3D4
Properties for the Result Resource

In the table below we have provided all of the attributes included in the Result 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)
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. x eq
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.
durationMode enumeration This property highlights the style of duration used for the test session. Returned values are: 'Timed' and 'Timed Sections'. 
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.
scaleScoreMapping resource A link to the full scale score mapping that was used for this test.
learningOutcomeThreshold int The sum of marks assigned to learning outcomes that is 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 identifying 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 / 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 / markBreakdown collection A mark breakdown object is returned if marked learning outcomes are setup on an item. This will return marks that have been assigned to each learning outcome on an individual item within a result. 
sections / items / markBreakdown / name string The name of the marked learning outcome.
sections / items / markBreakdown / mark   int The mark assigned to the marked learning outcome.
sections / items / markBreakdown / availableMarks   int The total number of marks available for each marked learning outcome on an item.
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 candidate's response.
For quality review tests, you can also retrieve any comments added by reviewers using the <qualityReviewItemComment> and <qualityReviewExamComment> nodes.
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.
sections / sectionSelectorId int The unique reference for the section selector that this section was presented in. This can be referenced in the section selector collection. If null is returned then this was not delivered as an optional section.
sections / selected boolean This property identifies if a candidate has selected this section if given the choice. Standard sections will display null, this is where the candidate was not given a choice.
sections / startTime dateTime The time a section was started by the candidate during delivery. For this setting to be recorded the test must be setup to have 'Enable Candidate logging' selected and for the duration type of the test form to be 'Timed Sections'. 
sections / endTime dateTime The time a section was completed by the candidate during delivery. For this setting to be recorded the test must be setup to have 'Enable Candidate logging' selected and for the duration type of the test form to be 'Timed Sections'.
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).
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 Item Authoring / Test Creation process and therefore not affect the result.
learningOutcomeBoundaries / passPercentage int The pass percentage for this learning outcome boundary.
sectionSelectors collection A collection of section selectors that were presented to the candidate during the test.
sectionSelectors / id
int The unique id of the section selector.
sectionSelectors / name   string The name of the section selector.
sectionSelectors / description   string The description presented to the candidate for the section selector.
sectionSelectors / duration   int The duration a candidate has to select a required section.
sectionSelectors / requiredSections   int The number of required sections a candidate must answer for each section selector screen within the test.
Show Analysis Property

When using a GET, you can pass an additional 'showAnalysis' parameter as 'true', this will show an additional breakdown on candidate achievement against Unit and Learning Outcome information you have applied to items in your test. Below is the information you will receive.
Attribute Name Type Description
unitName string The name of the unit assigned to the test. If none is assigned this will be ‘Unknown’.
attemptCount int The number of times an item with this unit (and/or associated learning outcomes) was attempted.
correctCount int The number of times an item with this unit (and/or associated learning outcomes) was answered correctly.
totalMark decimal The total number of marks available for all items with this unit.
userMark decimal The total number of marks the candidate achieved for all items with this unit (and/or associated learning outcomes).
learningOutcomes category A collection of learning outcomes that have been assigned to items within the test. 
learningOutcomes /
learningOutcomeName
string The name of the learning outcome assigned to the test. If none is assigned, this will be blank.
learningOutcomes /
attemptCount
int The number of times an item with this learning outcome was attempted.
learningOutcomes /
correctCount
int The number of times an item with this learning outcome was answered correctly.
learningOutcomes /
totalMark
decimal The total number of marks for all items that have this learning outcome assigned.
learningOutcomes /
userMark
decimal The total number of marks the candidate achieved for all items with this learning outcome.
learningOutcomes /
score
string Populated if the 'Show 'Result' Column' setting is enabled in 'Test Creation'.

Additional Notes
  • When filtering results you can use the same attribute twice. This is useful for propterties 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/Result?$filter=warehousedDate ge 08/06/2015T00:00:00 and warehousedDate le 09/06/2015T00:00:00

  • Tests that have been scheduled through the Surpass API with the markedExternally attribute passed as "True" will not be returned when calling the GET method for the Result Resource unless specifically requested in the URL. E.g.
https://...surpass.com/api/v2/Result?$top=10&$skip=0&$filter=subject/reference eq 'JLTS'&markedExternally=true

  • The Result 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 result 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/Result/{Keycode/ID}?showItemResponses=true - returns full result request including the item response model
https://...surpass.comapi/v2/Result/{Keycode/ID}/ItemResponse/{Item Authoring ID} - returns the response for one item
https://...surpass.comapi/v2/Result/{Keycode/ID}/ItemResponse/ - returns a list of the item response URLs contained within a result


GET Result Request and Return

The Result 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". 



Filtering results on Resource objects

The GET Result method allows you to filter on resource objects contained within the Result Resource. Subjects, centres, tests, test forms and candidates for that test 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/Result?$filter=subject/reference eq 'subject ref 1' and centre/reference eq 'centre ref 1’
https://...surpass.com/api/v2/Result?$filter=subject/id eq 21 and centre/id eq 25


Item Response Resource

Candidates' responses are returned as part of the result 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:



Required Permissions

To successfully call the Result methods, 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.

Feedback and Knowledge Base