Item Response Resource
The purpose of this resource is to make the raw data that we currently supply in the result request more useful to the consuming application and therefore provide more information that can be used in external auditing and reporting systems.
Item Response Requests
The Item Response resource extends the result, analytics and historical result resources and therefore can only be called if the relevant result information has been supplied in the request URL. If the Item Response resource is supplied without a specific Item Authoring reference then all Item Response URLs for a particular result are returned. This will then require another request to each individual item response to retrieve the desired model. An example of these requests have been supplied below:
https://....surpass.com/api/v2/result/{keycode}/itemResponse/
https://....surpass.com/api/v2/result/{keycode}/itemResponse/{ItemAuthoringId}
Additionally to this we also allow users to request the Item Response model for all items within a particular result by passing the parameter 'showItemResponses=true' as part of the result request URL. This will be returned within the Item collection. An example of this request has been provided below:
https://....surpass.com/api/v2/result/{keycode}?showItemResponses=true
Below we have provided all possible GET Item Response request URLs:
- api/v2/TestSession/{keycode}/ItemMarks
- api/v2/TestSession/{keycode}/ItemResponses
- api/v2/result/{keycode}/itemResponse/
- api/v2/result/{id}/itemResponse/
- api/v2/result/{keycode}/itemResponse/{ItemAuthoringId}
- api/v2/result/{id}/itemResponse/{ItemAuthoringId}
- api/v2/AnalyticsResult/{keycode}/itemResponse/
- api/v2/AnalyticsResult/{id}/itemResponse/
- api/v2/AnalyticsResult/{keycode}/itemResponse/{ItemAuthoringId}
- api/v2/AnalyticsResult/{id}/itemResponse/{ItemAuthoringId}
- api/v2/HistoricalResult/{id}/itemResponse/
- api/v2/HistoricalResult/{id}/itemResponse/{ItemAuthoringId}
XML example
JSON example
Item Response models - Question types
The Item Response model is built to be consistent with the item resource so within the response we return a separate collection for each supported question type. This is because the model can differ between question types. Below we have defined the model and provided examples for each of these question types. At the itemResponse level of the response we provide only a list of the question types as collections (empty if it is not relevant) and the href for item response.
Multiple Choice Questions
Property Name | Type | Description |
---|---|---|
optionList | collection | A collection of the available answer options for the item |
optionList / id | int | The unique identifier for each answer option |
optionList / correct | boolean | A flag to identify if the answer option has been identified as correct |
optionList / selected | boolean | A flag to identify which option the candidate has selected |
optionList / htmlText | XML | The answer option text including the HTML formatting applied |
optionList / label | string | The label assigned to the answer option by the item author |
optionList / weightedMark | int | Any weighted mark that has been applied to an answer option |
optionList / requiresExtraInfo | boolean | A flag to identify if an answer box has been enabled for the answer option in ‘Item Authoring’. If enabled, the candidate must add further information if they select that answer option. Note: Can only apply to Multiple Choice survey questions in HTML delivery. |
optionList / extraInfo | string | The information the candidate has provided in the answer box. Note: Can only apply to Multiple Choice survey questions in HTML delivery. |
optionList / extraInfoLabel | string | The label that appears above the answer box for candidates in delivery. This is defined in ‘Item Authoring’. Note: Can only apply to Multiple Choice survey questions in HTML delivery. |
userMark | int | The mark awarded for the item between 0-1 |
markType | enumeration | The mark type for the item. Standard or Weighted are the available options |
awardedMark | int | The mark awarded for the item |
id | string | The unique Surpass Item Authoring reference for this item |
weighting | int | The weighting applied to this question on the page |
attempted | boolean | If the candidate has attempted the item |
- optionList / weightedMark will return null if MarkType is Standard
- optionList / correct will return null if markType is Weighted
XML Example
JSON Example
Multiple Response Questions
Property Name | Type | Description |
---|---|---|
combinations | collection | If combination answer options are used a list of the authored groups |
combinations / mark | int | The mark assigned to that combination of answer options |
combinations / selected | boolean | The combination that was selected |
combinations / options | collection | The answer options within that combination group |
combinations / options / id | int | The ID of the answer options in that combination group |
partialMarks | boolean | This flag identifies if a candidate can receive partial marks if they get one answer correct |
optionList | collection | A collection of the available answer options for the item |
optionList / id | id | The unique identifier for each answer option |
optionList / correct | boolean | A flag to identify if the answer option has been identified as correct |
optionList / selected | boolean | A flag to identify which option the candidate has selected |
optionList / htmlText | XML | The answer option text including the HTML formatting applied |
optionList / label | string | The label assigned to the answer option by the item author |
optionList / weightedMark | int | Any weighted mark that has been applied to an answer option |
userMark | int | The mark awarded for the item between 0-1 |
markType | Enumeration | The mark type for the item. Standard or Combination are the available options |
awardedMark | int | The mark awarded for the item |
id | string | The unique Surpass Item Authoring reference for this item |
weighting | int | The weighting applied to this question on the page |
attempted | boolean | If the candidate has attempted the item |
- The combinations collection will be empty unless MarkType is Combination
- If combination mark type is selected then there will not be a correct answer in the option list
- partialMark is not relevant is combination is selected
- weightedMark remains null and is not relevant to this model
Examples of the multiple response questions item response model for both JSON and XML can be found by selecting the below links:
XML Example
JSON Example
Either / Or Questions
Property Name | Type | Description |
---|---|---|
userMark | int | If combination answer options are used a list of the authored groups |
optionList | collection | A collection of the available answer options for the item |
optionList / id | id | The unique identifier for each answer option |
optionList / correct | boolean | A flag to identify if the answer option has been identified as correct |
optionList / selected | boolean | A flag to identify which option the candidate has selected |
optionList / htmlText | XML | The answer option text including the HTML formatting applied |
optionList / label | string | The label assigned to the answer option by the item author |
awardedMark | int | The mark awarded for the item |
id | string | The unique Surpass Item Authoring reference for this item |
weighting | int | The weighting applied to this question on the page |
attempted | boolean | If the candidate has attempted the item |
XML Example
JSON Example
Property Name | Type | Description |
---|---|---|
userMark | int | If combination answer options are used a list of the authored groups |
awardedMark | int | The mark awarded for the item |
id | string | The unique Surpass Item Authoring reference for this item |
weighting | int | The weighting applied to this question on the page |
attempted | boolean | If the candidate has attempted the item |
files | resource | The group of files the candidate uploaded. |
files / fileName | string | The name of the file given by the candidate in delivery. |
files / content | Base64 encoded string | The content of the file uploaded by the candidate. |
Short Answer and Numerical Entry
Property Name |
Type |
Description |
---|---|---|
type |
collection |
The type of mode selected for the item (either “Standard” or “Advanced”) |
awardedMark |
int |
The mark awarded for the item |
id |
int |
The item’s unique identifier. |
weighting |
int |
The weighting applied to this question on the page. |
attempted |
boolean |
Identifies if a candidate has attempted the item |
candidateResponse |
array |
The candidate’s response |
answerList / answers |
string |
The list of accepted answers. |
Extended Matching
Property Name |
Type |
Description |
---|---|---|
awardedMark |
int |
The mark awarded for the item |
id |
int |
The item’s unique identifier. |
weighting |
int |
The weighting applied to this question on the page. |
attempted |
boolean |
Identifies if a candidate has attempted the item |
linkingType |
collection |
The selected linking type in this item. |
weightedMarking |
boolean |
Identifies whether weighted marking has been applied. |
leftBoxes |
resource |
The available boxes in the left column of the item. |
leftBoxes / id |
Int |
The answer box’s unique identifier. |
leftBoxes / text |
string |
The answer box’s content. |
rightBoxes |
resource |
The available answer boxes in the right column of the item. |
rightBoxes / id |
Int |
The answer box’s unique identifier. |
rightBoxes / text |
string |
The answer box’s content. |
correctLinks |
resource |
The item’s correct links. |
correctLinks / leftBoxId |
int |
The correct left box. |
correctLinks / rightBoxId |
int |
The correct right box |
correctLinks / mark |
int |
The available mark. |
candidateResponse |
resource |
The candidate’s responses. |
candidateResponse / leftBoxId |
int |
The left box the candidate chose. |
candidateResponse / rightBoxId |
int |
The right box the candidate chose. |
candidateResponse / mark |
int |
The mark the candidate received. |
Hotspot
Property Name |
Type |
Description |
---|---|---|
awardedMark |
int |
The mark awarded for the item |
id |
int |
The item’s unique identifier. |
weighting |
int |
The weighting applied to this question on the page. |
attempted |
boolean |
Identifies if a candidate has attempted the item |
type |
collection |
Identifies whether the correct area is a rectangle or polygon. |
weightedMarking |
boolean |
Identifies whether weighted marking has been applied. |
candidateResponse |
collection |
The candidate’s response. |
candidateResponse / co-ordinates |
int |
The screen co-ordinates of the candidate’s selection. |
Essay
Property Name |
Type |
Description |
---|---|---|
awardedMark |
int |
The mark awarded for the item |
id |
int |
The item’s unique identifier. |
weighting |
int |
The weighting applied to this question on the page. |
attempted |
boolean |
Identifies if a candidate has attempted the item |
candidateResponse |
collection |
The candidate’s response. |
candidateResponse / response |
string |
The text of the candidate’s response. |
Unsupported Question Types
Property Name | Type | Description |
---|---|---|
awardedMark | int | The mark awarded for the item |
id | string | The unique Surpass Item Authoring reference for this item |
weighting | int | The weighting applied to this question on the page |
attempted | boolean | If the candidate has attempted the item |
XML Example
JSON Example
Property Name | Type | Description |
---|---|---|
itemId | string | The Surpass item ID for the test. |
mark | int | The mark the candidate achieved for an item. |
notAttempted | boolean | Shows whether or not the candidate attempted the question. If marked as 'true' the candidate will achieve no marks. |
Property Name | Type | Description |
---|---|---|
questionNumber | string | The position of the question in the test. |
answer | string | The response provided by the candidate to the item. |