ItemExposure API

The ItemExposure API lets you see which items a specified candidate has already seen in tests.

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

Import this API into your Postman Workspace

Listing items seen by a specified candidate

get /api/v2/ItemExposure/Candidate?id={id}

Send a request to the endpoint to retrieve a list of items seen by a specific candidate using either their ID or reference. Refer to the available parameters to influence the response. No request body is required.

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	query OPTIONAL	`/api/v2/ItemExposure/Candidate?id={id}`	Returns information for the specified candidate, where `{id}` is the candidate’s unique identifier.
reference	query OPTIONAL	`/api/v2/ItemExposure/Candidate?reference={reference}`	Returns information for the specified candidate, where `{reference}` is the candidate’s unique reference code.
filter	query OPTIONAL	`/api/v2/ItemExposure/Candidate?id={id}&filter={filter} {operator} {value}`	Filters results for an exact match. For an exact match: `{id}` is the candidate’s unique identifier; `{filter}` is one of `testId`, `testReference`; `{operator}` is `eq` (equal to); and `'{value}'` is the string or integer the filter query looks for an exact match for 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.

{
    "candidate": {
        "id": 1,
        "reference": "Candidate1"
    },
    "item": [
        {
            "id": "0001P0001",
            "totalAppearances": 3,
            "tests": [
                {
                    "id": 1,
                    "testForms": [
                        {
                            "id": 1,
                            "appearances": 1
                        },
                        {
                            "id": 2,
                            "appearances": 1
                        }
                    ]
                },
                {
                    "id": 2,
                    "testForms": [
                        {
                            "id": 3,
                            "appearances": 1
                        }
                    ]
                }
            ]
        },
        {
            "id": "0001P002",
            "totalAppearances": 2,
            "tests": [
                {
                    "id": 2,
                    "testForms": [
                        {
                            "id": 4,
                            "appearances": 1
                        },
                        {
                            "id": 5,
                            "appearances": 1
                        }
                    ]
                }
            ]
        },
        {
            "id": "0001P0003",
            "totalAppearances": 3,
            "tests": [
                {
                    "id": 3,
                    "testForms": [
                        {
                            "id": 6,
                            "appearances": 1
                        },
                        {
                            "id": 7,
                            "appearances": 1
                        }
                    ]
                },
                {
                    "id": 4,
                    "testForms": [
                        {
                            "id": 8,
                            "appearances": 1
                        }
                    ]
                }
            ]
        }
    ]
}

EXAMPLE: In the above example, candidate 1 has seen:

Item 0001P0001 3x (on test forms 1 and 2 of test 1, and test form 3 of test 2)
Item 0001P0002 2x (on test forms 4 and 5 of test 2)
Item 0001P0003 3x (on test forms 6 and 7 of test 3, and test form 8 of test 4)

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.
InaccessibleCandidate	13	The candidate defined in the request cannot be accessed.
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.

ItemExposure API

In This Article

Listing items seen by a specified candidate

Parameters

Sample response

Response schema

Error Codes

About the site