SummaryResult API

Results contain all of the information from a candidate’s completed script, including the candidate’s responses and interactions with the test driver. The SummaryResult resource is a more concise overview of results information.

The SummaryResult API resource is used to list and retrieve results.

This article explains what calls can be made to the Surpass API using the SummaryResult resource.

Import this API into your Postman Workspace

Listing results

get /api/v2/SummaryResult

Send a request to the endpoint to retrieve a list of results. 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.

EXAMPLE: The endpoint /api/v2/SummaryResult?$filter=subject/id eq 1 would return results for all the results in subject 1.

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/SummaryResult?$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/SummaryResult?$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/SummaryResult?$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`, `centre/id`, `centre/reference`, `test/id`, `test/reference`, `testForm/id`, `testForm/reference`, `candidate/id`, `candidate/reference`, `keycode`, `{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 `startedDate`, `submittedDate`, `warehousedDate`, `{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 `startedDate`, `submittedDate`, `warehousedDate`, `{operator}` is `le` (less than), and `{value}` is the string (in DD/MM/YYYY format) the filter looks for less than in the request.
markedExternally	query OPTIONAL	`/api/v2/SummaryResult?markedExternally={Boolean}`	Determines whether to include results for test sessions with the `markedExternally` property set to `true` (at the point of scheduling) in the response, where `{Boolean}` is one of `true` or `false`.
includeExamsInMarking	query OPTIONAL	`/api/v2/SummaryResult?includeExamsInMarking={Boolean}`	Determines whether to include results awaiting to be released from SecureMarker in the response, where `{Boolean}` is one of `true` or `false`.

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top, skip, and other parameters are joined using &. For example, the endpoint /api/v2/SummaryResult?$top=10&$skip=25 would skip the first 25 results and return 10.

TIP: You can search for all results started (startedDate), submitted (submittedDate), or warehoused (warehousedDate) between two dates using the following format: /api/v2/SummaryResult?$filter=startedDate ge DD/MM/YYYY and startedDate le DD/MM/YYYY.

TIP: You can also search for all results at a particular centre and subject combination by using the following format: /api/v2/SummaryResult?$filter=subject/id eq 1 and centre/id eq 1.

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": 3711,
    "top": 10,
    "skip": 0,
    "pageCount": 372,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/SummaryResult?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "reference": "3RTTPP4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/1"
        },
        {
            "id": 2,
            "reference": "9B7BPM4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/2"
        },
        {
            "id": 3,
            "reference": "VHMYVW4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/3"
        },
        {
            "id": 4,
            "reference": "FD6R6F4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/4"
        },
        {
            "id": 5,
            "reference": "QDGNCM4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/5"
        },
        {
            "id": 6,
            "reference": "RFBF6D4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/6"
        },
        {
            "id": 7,
            "reference": "QMQ64G4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/7"
        },
        {
            "id": 8,
            "reference": "GYN7XB4S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/8"
        },
        {
            "id": 9,
            "reference": "ND73Q94S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/9"
        },
        {
            "id": 10,
            "reference": "8TMKK44S",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/10"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Retrieving result information

get /api/v2/SummaryResult/{id}

Send a request to the endpoint to retrieve information for a specific result using either its ID or the candidate’s unique keycode. No request body is required.

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/SummaryResult/{id}`	Returns information for the specified result, where `{id}` is the result’s unique identifier.
keycode	path OPTIONAL	`/api/v2/SummaryResult/{keycode}`	Returns information for the specified result, where `{keycode}` is the candidate’s unique keycode used to enter the test.

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": [
        {
            "test": {
                "id": 1,
                "reference": "Test1",
                "href": "https:/{your Surpass instance}.surpass.com/api/v2/Test/1"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "href": ""
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Centre/1"
            },
            "candidate": {
                "id": 1,
                "reference": "Candidate1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Candidate/1"
            },
            "mark": 32.333,
            "availableMarks": 52,
            "grade": "Distinction",
            "startedDate": "2022-03-07T15:46:43.937",
            "submittedDate": "2022-03-07T15:51:00",
            "warehousedDate": "2022-03-08T08:57:52.963",
            "id": 5755,
            "reference": "H8JBWWX8",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/SummaryResult/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 results there are in total. This is null because the information retrieved is for a specific result.

top integer

Details number of results returned in the response. This is null because the information retrieved is for a specific result.

skip integer

Details how many results were skipped to display those in the response. This is null because the information retrieved is for a specific result.

pageCount integer

Details how many pages of results there are. This is null because the information retrieved is for a specific result.

nextPageLink string

The endpoint to call the next page of results. This is null because the information retrieved is for a specific result.

prevPageLink string

The endpoint to call the previous page of results. This is null because the information retrieved is for a specific result.

response array

Contains the rest of the response.

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.

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.

centre object

Contains the centre’s information.

centre/id integer

The centre’s unique identifier.

centre/reference string

The candidate’s unique reference code.

centre/href string

The endpoint to call the centre’s information, such as /api/v2/Centre/{id} where {id} is the centre’s unique identifier.

candidate object

Contains the candidate’s information.

candidate/id integer

The candidate’s unique identifier.

candidate/reference string

The candidate’s unique reference code.

candidate/href string

The endpoint to call the candidate’s information, such as /api/v2/Candidate/{id} where {id} is the candidate’s unique identifier.

mark integer

The total mark achieved by the candidate.

availableMarks integer

The total available marks.

grade string

The grade the candidate achieved.

startedDate string

The date and time the candidate started the test, in YYYY-MM-DDTHH:SS format.

submittedDate string

The date and time the candidate submitted the test, in YYYY-MM-DDTHH:SS format.

warehousedDate string

The date and time the test was warehoused, in YYYY-MM-DDTHH:SS format.

id integer

The result’s unique identifier.

reference string

The result’s unique reference code. This is the same as the candidate’s unique keycode used to enter the test.

href string

The endpoint to call the result’s information, such as /api/v2/Result/{id} where {id} is the result’s unique identifier.

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.
InvalidReference	11	The unique reference code used in the request is invalid.
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/SummaryResult?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.
ResultDoesNotExist	30	The result specified in the request does not exist.

SummaryResult API

In This Article

Listing results

Parameters

Sample response

Response schema

Retrieving result information

Parameters

Sample response

Response schema

Error Codes

Further reading

About the site