RescoringRule API
In Surpass, the Rescoring screen is where you can reduce the impact of incorrect and invalid items. In a rescoring session, you can award full marks to items, add and remove scores, and change the correct answer options. The RescoringRule resource returns information from these rescoring sessions.
The RescoringRule API resource is used to list and retrieve rescoring sessions.
This article explains what calls can be made to the Surpass API using the RescoringRule resource.
Import this API into your Postman Workspace
In This Article
Listing rescoring sessions
Send a request to the endpoint to retrieve a list of rescoring sessions. Refer to the available parameters to influence the response. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
top |
query OPTIONAL |
/api/v2/RescoringRule?$top={top} |
Defines number of responses to return when paging a response, where {top} is a number between 1 and 40. |
|
skip |
query OPTIONAL |
/api/v2/RescoringRule?$skip={skip} |
Defines how many responses to skip when paging a response, where {skip} is a number that should not exceed the total number of responses. |
|
filter |
query OPTIONAL |
/api/v2/RescoringRule?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of subject/id, subject/reference, test/id, test/reference, testForm/id, testForm/reference; {operator} is eq (equal to); and {value} is the string or integer the filter query looks for an exact match for in the request. For a greater than query: {filter} is savedDate, {operator} is ge (greater than), and {value} is the string (in DD/MM/YYYY format) the filter looks for more than in the request. For a less than query: {filter} is savedDate, {operator} is le (less than), and {value} is the string (in DD/MM/YYYY format) the filter looks for less than in the request. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": 25,
"top": 10,
"skip": 0,
"pageCount": 3,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/RescoringRule?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/1"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/2"
},
{
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/3"
},
{
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/4"
},
{
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/5"
},
{
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/6"
},
{
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/7"
},
{
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/8"
},
{
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/9"
},
{
"id": 10,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/10"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many rescoring sessions there are in total.
top integer
Details number of rescoring sessions returned in the response.
skip integer
Details how many rescoring sessions were skipped to display those in the response.
pageCount integer
Details how many pages of rescoring sessions there are.
nextPageLink string
The endpoint to call the next page of rescoring sessions. If null, the response is the last page of rescoring sessions.
prevPageLink string
The endpoint to call the previous page of rescoring sessions. If null, the response is the first page of rescoring sessions.
response array
Contains the rest of the response.
id integer
The rescoring session’s unique identifier.
href string
The endpoint to call the rescoring session’s information, such as /api/v2/RescoringRule/{id} where {id} is the rescoring session’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving rescoring session information
Send a request to the endpoint to retrieve information for a specific rescoring session using either its ID or reference. No request body is required.
Parameters
Parameters are passed with the endpoint to influence the response. Header parameters are included in the request header. Path parameters are extensions of the endpoint, and query parameters follow ? after any path parameters.
|
Name |
Parameter |
Input |
Description |
|---|---|---|---|
|
authorization |
header MANDATORY |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
id |
path OPTIONAL |
/api/v2/RescoringRule/{id} |
Returns information for the specified rescoring session, where {id} is the rescoring session’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/RescoringRule?reference={reference} |
Returns information for the specified rescoring session, where {reference} is the rescoring session’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the information in either JSON or XML format as requested.
{
"count": null,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"rescoredItems": [
{
"rescoredItem": {
"originalItemMarkType": "Standard",
"answerOptions": [
{
"label": "A",
"displayLabel": "A",
"contentType": "RichText",
"originalMark": 1,
"newMark": null,
"exclusiveOption": false
},
{
"label": "B",
"displayLabel": "B",
"contentType": "RichText",
"originalMark": 0,
"newMark": null,
"exclusiveOption": false
},
{
"label": "C",
"displayLabel": "C",
"contentType": "RichText",
"originalMark": 1,
"newMark": null,
"exclusiveOption": false
},
{
"label": "D",
"displayLabel": "D",
"contentType": "RichText",
"originalMark": 0,
"newMark": null,
"exclusiveOption": false
},
{
"label": "E",
"displayLabel": "E",
"contentType": "RichText",
"originalMark": 1,
"newMark": null,
"exclusiveOption": false
},
{
"label": "F",
"displayLabel": "F",
"contentType": "RichText",
"originalMark": 0,
"newMark": null,
"exclusiveOption": false
}
],
"itemId": "5145P1",
"originalOnlyAwardIfAllCorrect": false,
"itemVersion": 2,
"newOnlyAwardIfAllCorrect": false,
"type": "MultipleResponse",
"questionText": "Which of the following cities are in the Netherlands?",
"totalMark": 1,
"combinations": [
{
"name": "Combination 1",
"mark": 1,
"answerOptions": [
{
"label": "F",
"displayLabel": "F",
"contentType": "RichText",
"originalMark": 0,
"newMark": null,
"exclusiveOption": false
}
]
}
],
"contentType": "RichText",
"unattemptedMark": null
},
"changeAction": "AnswerChanged"
},
{
"rescoredItem": {
"itemId": "5145P2",
"itemVersion": 2,
"type": "FillInTheBlank",
"questionText": "Complete the following sentence.",
"totalMark": 1,
"contentType": "RichText",
"unattemptedMark": null
},
"changeAction": "FullMarked"
},
{
"rescoredItem": {
"itemId": "5145P3",
"itemVersion": 2,
"type": "DragAndDrop",
"questionText": "Drag the European countries into the drop zone.",
"totalMark": 1,
"contentType": "RichText",
"unattemptedMark": null
},
"changeAction": "FullMarkedUnattempted"
},
{
"rescoredItem": {
"itemId": "5145P4",
"itemVersion": 2,
"type": "NumericalEntry",
"questionText": "What is the square root of 64?",
"totalMark": 1,
"contentType": "RichText",
"unattemptedMark": null
},
"changeAction": "Added"
},
{
"rescoredItem": {
"itemId": "5145P5",
"itemVersion": 2,
"type": "SelectFromAList",
"questionText": "Complete the following sentence.",
"totalMark": 1,
"contentType": "RichText",
"unattemptedMark": null
},
"changeAction": "Deleted"
}
],
"user": {
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/95"
},
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/145",
"name": null
},
"test": {
"id": 1,
"reference": "Test1",
"href": null
},
"testForm": {
"id": 1,
"reference": "TestForm1",
"href": null
},
"startDate": "2016-10-12T00:00:00",
"endDate": "2016-10-12T23:59:59",
"savedDate": "2016-10-13T10:01:38.81",
"historicalResults": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/HistoricalResult/1"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/HistoricalResult/2"
}
],
"scoringData": [
{
"testFormVersion": 2,
"scaleScoreMapping": null,
"gradeBoundaries": {
"minRawScore": 2.0000,
"grade": "C minus"
},
"loBoundaries": null
},
{
"testFormVersion": 4,
"scaleScoreMapping": null,
"gradeBoundaries": null,
"loBoundaries": null
}
],
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/RescoringRule/1"
}
],
"errors": null,
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
count integer
Details how many rescoring sessions there are in total. This is null because the information retrieved is for a specific rescoring session.
top integer
Details number of rescoring sessions returned in the response. This is null because the information retrieved is for a specific rescoring session.
skip integer
Details how many rescoring sessions were skipped to display those in the response. This is null because the information retrieved is for a specific rescoring session.
pageCount integer
Details how many pages of rescoring sessions there are. This is null because the information retrieved is for a specific rescoring session.
nextPageLink string
The endpoint to call the next page of rescoring sessions. This is null because the information retrieved is for a specific rescoring session.
prevPageLink string
The endpoint to call the previous page of rescoring sessions. This is null because the information retrieved is for a specific rescoring session.
response array
Contains the rest of the response.
rescoredItems array
Contains information for any rescored items.
rescoredItems/rescoredItem object
Contains the rescored item’s information.
rescoredItems/rescoredItem/originalItemMarkType enumeration
Determines whether the Marking type for the question is Standard or Weighted.
rescoredItems/rescoredItem/answerOptions array
If the item is a Multiple Choice, Multiple Response, or Either/Or question, contains information for the item’s answer options.
A separate object is returned for each answer option.
rescoredItems/rescoredItem/answerOptions/label string
The answer option’s label.
rescoredItems/rescoredItem/answerOptions/displayLabel string
The answer option’s display label.
rescoredItems/rescoredItem/answerOptions/contentType enumeration
Determines the content type for the answer option. This can be either RichText, an Image, or MathML.
rescoredItems/rescoredItem/answerOptions/originalMark integer
The answer option’s original mark.
rescoredItems/rescoredItem/answerOptions/newMark integer
The answer option’s new mark.
rescoredItems/rescoredItem/answerOptions/exclusiveOption Boolean
Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.
rescoredItems/rescoredItem/itemId string
The item’s unique identifier.
rescoredItems/rescoredItem/originalOnlyAwardIfAllCorrect Boolean
If the item is a Multiple Choice or Multiple Response question, determines whether the Only award mark if candidate selects all correct options setting was originally enabled (true) or not (false).
rescoredItems/rescoredItem/itemVersion integer
The item’s version.
rescoredItems/rescoredItem/newOnlyAwardIfAllCorrect Boolean
If the item is a Multiple Choice or Multiple Response question, determines whether the Only award mark if candidate selects all correct options setting is now enabled (true) or not (false).
rescoredItems/rescoredItem/type enumeration
The item type, which can be one of MultipleChoice, MultipleResponse, EitherOr, NumericalEntry, FillInTheBlank, ShortAnswer, Essay, SelectFromAList, MatchingBoxes (Extended Matching questions), FileAttach, DragAndDrop, EquationEntry, HotSpot, Spreadsheet, VoiceCapture, CqtItem (Custom Question type questions), FractionEntryItem, MultipleChoiceSurvey, MultipleResponseSurvey, or Likert.
rescoredItems/rescoredItem/questionText string
The item’s question text.
”rescoredItems/rescoredItem/totalMark” ”integer”}
rescoredItems/rescoredItem/combinations array
Contains the answer option combinations’ information if the Marking type is set to Combination.
rescoredItems/rescoredItem/combinations/name string
The answer combination’s name.
rescoredItems/rescoredItem/combinations/mark integer
The answer combination’s name,
rescoredItems/rescoredItem/combinations/answerOptions array
Contains information for the item’s answer options. A separate object is returned for each answer option.
rescoredItems/rescoredItem/combinations/answerOptions/label string
The answer option’s label.
rescoredItems/rescoredItem/combinations/answerOptions/displayLabel string
The answer option’s display label.
rescoredItems/rescoredItem/combinations/answerOptions/contentType enumeration
Determines the content type for the answer option. This can be either RichText, an Image, or MathML.
rescoredItems/rescoredItem/combinations/answerOptions/originalMark integer
The answer option’s original mark.
rescoredItems/rescoredItem/combinations/answerOptions/newMark integer
The answer option’s new mark.
rescoredItems/rescoredItem/combinations/answerOptions/exclusiveOption Boolean
Determines whether the answer option is set to be an Exclusive Option, meaning it cannot be selected in conjunction with other answer options.
rescoredItems/rescoredItem/contentType enumeration
Determines the content type for the answer option. This can be either RichText, an Image, or MathML.
rescoredItems/rescoredItem/unattemptedMark integer
The mark assigned if the question was unattempted.
rescoredItems/changeAction enumeration
Determines the change made to the item during the rescoring session. The available values are:
- Added – Marks were added to the item.
- AnswerChanged – One or more answer options were changed.
- Deleted – Marks were removed from the item.
- FullMarked – The item was assigned full marks.
- FullMarkedUnattempted – The item was assigned full marks even if candidates did not attempt the question.
user object
Contains the information for the user who rescored the result.
user/id integer
The user’s unique identifier.
user/reference string
The user’s unique reference code.
user/href string
The endpoint to call the user’s information, such as /api/v2/User/{id} where {id} is the user’s unique identifier.
subject object
Contains the subject’s information.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject/{id} where {id} is the subject’s unique identifier.
subject/name string
The subject’s name.
test object
Contains the test’s information.
test/id integer
The test’s unique identifier.
test/reference string
The test’s unique reference code.
test/href string
The endpoint to call the test’s information, such as /api/v2/Test/{id} where {id} is the test’s unique identifier.
testForm object
Contains the test form’s information.
testForm/id integer
The test form’s unique identifier.
testForm/reference string
The test form’s unique reference code.
testForm/href string
The endpoint to call the test form’s information, such as /api/v2/TestForm/{id} where {id} is the test form’s unique identifier.
startDate string
The date the rescoring session started, in YYYY-MM-DDTHH:SS format.
endDate string
The date the rescoring session ended, in YYYY-MM-DDTHH:SS format.
savedDate string
The date the rescoring session was saved, in YYYY-MM-DDTHH:SS format.
historicalResults array
Contains any historical results’ information. Each historical result is a record of the result in the state it was in between rescoring sessions.
historicalResults/id id
The result’s unique identifier.
historicalResults/href string
The endpoint to call the result’s information, such as /api/v2/HistoricalResult/{id} where {id} is the result’s unique identifier.
scoringData array
Contains the scoring data information.
scoringData/testFormVersion integer
The test form’s version.
scoringData/scaleScoreMapping object
scoringData/gradeBoundaries object
Contains the grade boundaries’ information. For more information on grade boundaries, read Setting up grade boundaries.
scoringData/gradeBoundaries/minRawScore integer
The minimum raw score needed for candidates to pass the test.
scoringData/gradeBoundaries/grade string
The grade achieved by the candidate.
scoringData/loBoundaries array
Contains the information of any Learning Outcomes included in Learning Outcome Boundaries assigned to items in the test. For more information on grade boundaries, read Setting up grade boundaries.
scoringData/loBoundaries/learningOutcomeBoundariesApplied Boolean
Determines whether Learning Outcome Boundaries have been applied (the learningOutcomeThreshold value has been exceeded). If true, Learning Outcome Boundaries have been applied.
scoringData/loBoundaries/learningOutcomeBoundaries object
The Learning Outcome Boundaries applied during the rescoring session. A separate object is returned for each learning outcome.
scoringData/loBoundaries/learningOutcomeBoundaries/isDefault Boolean
Determines whether the default pass mark for Learning Outcome Boundaries was applied. If false, a custom Learning Outcome Boundary pass mark was applied by the test creator.
scoringData/loBoundaries/learningOutcomeBoundaries/text string
The Learning Boundary’s name. This must match the Learning Outcome tag value for Learning Outcome Boundaries to work correctly.
scoringData/loBoundaries/learningOutcomeBoundaries/passPercentage string
The pass percentage required to pass the Learning Outcome.
id integer
The rescoring session’s unique identifier.
href string
The endpoint to call the rescoring session’s information, such as /api/v2/RescoringRule/{id} where {id} is the rescoring session’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Name |
Code |
Description |
|---|---|---|
|
InternalServer |
1 |
Internal server error. |
|
Unauthorized |
3 |
The request has been sent by an unauthorised user. |
|
IncorrectFieldFormat |
4 |
A field in the request has not been completed in the correct format. |
|
InaccessibleOperation |
5 |
The request has been sent by a user with invalid permissions. |
|
InaccessibleData |
6 |
The request has been sent by a user with invalid permissions. |
|
MissingBody |
7 |
There is an issue with the request body. |
|
InvalidInputParameters |
15 |
There is an issue with the path or query parameters. |
|
InvalidId |
16 |
The ID number used in the request is invalid. |
|
InvalidODataOperation |
19 |
There is an issue with the query parameters. |
|
BadRequest |
20 |
There is an issue with the /api/v2/RescoringRule?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: