AnalyticsResult OAPI

The result returned by the AnalyticsResult resource is the latest version of a result in Reporting. If any changes have taken place in Reporting, this resource provides the latest result data.

The AnalyticsResult OAPI resource is used to list and retrieve results and item responses.

This article explains what calls can be made to the Surpass OAPI using the AnalyticsResult OAPI resource.

Import this API into your Postman Workspace

Listing results

get /oapi/AnalyticsResult

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
filter	query OPTIONAL	`/oapi/AnalyticsResult?filter={filter} {operator} {value}`	Filters results, searching for an exact match or for the data to contain a defined value. For an exact match: `{filter}` is one of `keycode`, `candidate.id`, `candidate.reference`, `test.id`, `test.reference`, `test.name`, `testForm.id`, `testForm.reference`, `testForm.name`, `subject.id`, `subject.reference`, `subject.name`, `centre.id`, `centre.reference`, `centre.name`; `{operator}` is `eq` (equal to); and `{value}` is the string, Boolean, or integer the filter query looks for an exact match for in the request. For a greater than query: `{filter}` is `candidate.id`, `test.id`, `testForm.id`, `subject.id`, `centre.id`; `{operator}` is `ge` (greater than); and `{value}` is the integer the filter looks for more than in the request. For a less than query: `{filter}` is `candidate.id`, `test.id`, `testForm.id`, `subject.id`, `centre.id`; `{operator}` is `le` (less than); and `{value}` is the integer the filter looks for less than in the request. For a contains query: `{filter}` is one of `keycode`, `candidate.reference`, `test.reference`, `test.name`, `testform.reference`, `testform.name`, `subject.name`, `subject.reference`, `centre.name`, `centre.reference`; `{operator}` is `contains`; and `{value}` is the string or integer the filter query looks for an exact match for in the request.
orderBy	query	`/oapi/AnalyticsResult?orderBy=fieldName={fieldName}&ascending={operator}`	Determines order of results, where `{fieldName}` is one of `keycode`, `dateTaken`, `candidate.id`, `test.id`, `testForm.id`, `subject.id`, `centre.id`; and `{operator}` is `true` or `false`.

TIP: Multiple query parameters can be joined using &, for example the endpoint /oapi/AnalyticsResult?$take=10&$skip=25 would skip the first 25 results and return 10.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the information requested.

{
    "count": 5468,
    "top": 10,
    "skip": 0,
    "totalPages": 547,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/AnalyticsResult?Skip=10&Take=10",
    "previousPageLink": null,
    "results": [
        {
            "keycode": "XCGJDGXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 1,
                "reference": "Candidate1"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "XDP9CQXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 2,
                "reference": "Candidate2"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "RDYFJXXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 3,
                "reference": "Candidate3"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "C9MHD8XX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 4,
                "reference": "Candidate4"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "Y3FMP8XX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 5,
                "reference": "Candidate5"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "C8RRCNXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 6,
                "reference": "Candidate6"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "VNVBBTXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 7,
                "reference": "Candidate7"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "PRFN9LXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 8,
                "reference": "Candidate8"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "FF8B3NXX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 9,
                "reference": "Candidate9"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        },
        {
            "keycode": "XFLWK4XX",
            "dateTaken": 2022-09-26T13:29:48.363,
            "candidate": {
                "id": 10,
                "reference": "Candidate10"
            },
            "test": {
                "id": 1,
                "reference": "Test1",
                "name": "Final Year Geography Test"
            },
            "testForm": {
                "id": 1,
                "reference": "TestForm1",
                "name": "Final Year Geography Test Form January 2022"
            },
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject"
            },
            "centre": {
                "id": 1,
                "reference": "Centre1",
                "name": "Surpass Centre"
            }
        }
    ],
    "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.

top integer

Details number of results returned in the response.

skip integer

Details how many results were skipped to display those in the response.

totalPages integer

Details how many pages of results there are.

nextPageLink string

The endpoint to call the next page of results. If null, the response is the last page of results.

previousPageLink string

The endpoint to call the previous page of results. If null, the response is the first page of results.

results array

Contains the rest of the response.

NOTE: If the response contains multiple results, a separate object is returned for each result.

keycode string

The candidate’s unique keycode, used to enter their test.

dateTaken string

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

candidate object

Contains the candidate’s information.

candidate/id integer

The candidate’s unique identifier.

candidate/reference string

The candidate’s unique reference code.

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/name string

The test’s name.

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/name string

The test form’s name.

subject object

Contains the subject’s information.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

subject/name string

The subject’s name.

centre object

Contains the centre’s information.

centre/id integer

The centre’s unique identifier.

centre/reference string

The centre’s unique reference code.

centre/name string

The centre’s name.

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.