ItemSet API

Item sets are groups of items with “friend” relationships. Items with friend relationships cannot be added to a test without their friend items. Friend items always appear next to each other in tests and can share source material and question text, making them ideal for presenting a number of items on the same theme (such as in a case study).

The ItemSet API resource is used to list, retrieve, create, update, and delete item sets.

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

Import this API into your Postman Workspace

Listing item sets

get /api/v2/ItemSet

Send a request to the endpoint to retrieve a list of item sets. 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/ItemSet?$filter=subject/id eq '1' would return all item sets 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/ItemSet?$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/ItemSet?$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/ItemSet?$filter={filter} {operator} {value}`	Filters results, searching for an exact match. For an exact match: `{filter}` is one of `name`, `subject/id` or `subject/reference`, `parentFolderId`, `{operator}` is `eq` (equal to), and `{value}` is the string or integer the filter query looks for an exact match for in the request.

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/ItemSet?$top=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 in either JSON or XML format as requested.

{
    "count": 91,
    "top": 10,
    "skip": 0,
    "pageCount": 10,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/ItemSet?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/1"
        },
        {
            "id": 2,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/2"
        },
        {
            "id": 3,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/3"
        },
        {
            "id": 4,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/4"
        },
        {
            "id": 5,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/5"
        },
        {
            "id": 6,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/6"
        },
        {
            "id": 7,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/7"
        },
        {
            "id": 8,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/8"
        },
        {
            "id": 9,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/9"
        },
        {
            "id": 10,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/10"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Retrieving item set information

get /api/v2/ItemSet/{id}

Send a request to the endpoint to retrieve information for a specific item set using its ID. 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.

path

OPTIONAL

/api/v2/ItemSet/{id}

Returns information for the specified item set, where {id} is the item set’s unique identifier.

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": [
        {
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
                "name": null
            },
            "parentFolderId": -1,
            "position": 2,
            "name": "Item Set 1",
            "deleted": true,
            "allowRandomisation": false,
            "locked": false,
            "items": [],
            "sharedWith": [],
            "standardLists": [],
            "sourceMaterials": [],
            "owner": {
                "id": 1,
                "reference": "User1",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
            },
            "comment": "",
            "comments": [],
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/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 item sets there are in total. This is null because the information retrieved is for a specific item set.

top integer

Details number of item sets returned in the response. This is null because the information retrieved is for a specific item set.

skip integer

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

pageCount integer

Details how many pages of item sets there are. This is null because the information retrieved is for a specific item set.

nextPageLink string

The endpoint to call the next page of item sets. This is null because the information retrieved is for a specific item set.

prevPageLink string

The endpoint to call the previous page of item sets. This is null because the information retrieved is for a specific item set.

response array

Contains the rest of the response.

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.

parentFolderId integer

The folder’s unique identifier if the item set is in a folder.

position integer

The item set’s position within a folder if the item set is in a folder.

name string

The item set’s name.

deleted Boolean

Determines whether the item set is deleted.

allowRandomisation Boolean

Determines whether the Allow randomisation of item set setting is enabled. If true, the order of the items in the item set can be randomised when creating a test.

NOTE: If disabled, this property is not returned rather than returning as false.

locked Boolean

Determines whether the Fix the order of items setting is enabled. If true, the order of items in the item set cannot be rearranged.

items array

Contains any items in the item set.

NOTE: If the item set contains multiple items, a separate object for each item is returned.

items/id integer

The item’s unique identifier.

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.

href string

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

sharedWith array

Contains the information for any subject the item set is shared with.

NOTE: If the item is shared with multiple subjects, a separate object for each subject is returned.

sharedWith/id integer

The subject’s unique identifier.

sharedWith/reference string

The subject’s’s unique reference code.

sharedWith/href string

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

sharedWith/name string

The subject’s name.

NOTE: This is a retired property and therefore returns as null.

standardLists array

Contains the information for any item list the item set is a part of.

NOTE: If the item set is in multiple item lists, a separate object for each item list is returned.

standardLists/id integer

The item list’s unique identifier.

standardLists/reference string

The item list’s unique reference code.

standardLists/href string

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

sourceMaterials array optional

Contains any source material attached to the item set.

NOTE: If the item set contains multiple source materials, a separate object for each source material is returned.

sourceMaterials/externalId string

The source material’s name in Surpass.

sourceMaterials/id integer

The source material’s unique identifier.

owner object

The item set owner’s information.

owner/id integer

The item set owner’s unique identifier.

owner/reference string

The item set owner’s unique reference code.

owner/href string

The endpoint to call the item set owner’s information, such as /api/v2/User/{id} where {id} is the item set owner’s unique identifier.

comments array

Contains the information for any comments left on the item set.

NOTE: If the the item set contains multiple comments, a separate object for each comment is returned.

comments/id integer

The comment’s unique identifier.

comments/text string

The comment.

comments/private Boolean

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

comments/dateCreated string

The date the comment was left, in YYYY/MM/DD format.

comments/createdBy array

Contains the user who left the comment’s information.

comments/createdBy/id integer

The user’s unique identifier.

comments/createdBy/reference string

The user’s unique reference code.

comments/createdBy/href string

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

id integer

The item set’s unique identifier.

href string

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

errors string

Information about any errors that occurred during the request.

serverTimeZone enumeration

The timezone of the server sending the response.

Creating an item set

post /api/v2/ItemSet

Send a request to the endpoint to create an item set.

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.
content-type	header MANDATORY	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
content-length	header MANDATORY	`{number}`	Determines the number of characters passed in the body of the request, where `{number}` is a numerical figure. This is usually automatically calculated when the request is sent.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.

Sample request

The following request contains the minimum required request body to create an item set.

{
    "subject": {
        "reference": "Subject1"
    },
    "name": "Item Set 1"
}

EXAMPLE: In this sample request, an item set called ‘Item Set 1’ is created in Subject1.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

subject object mandatory

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.

parentFolderId integer optional

The folder’s unique identifier if the item set is in a folder.

position integer optional

The item set’s position within a folder if the item set is in a folder.

allowRandomisation Boolean optional

Determines whether the Allow randomisation of item set setting is enabled. If true, the order of the items in the item set can be randomised when creating a test.

locked Boolean optional

Determines whether the Fix the order of items setting is enabled. If true, the order of items in the item set cannot be rearranged.

items array optional

Contains any items in the item set.

NOTE: If the item set contains multiple items, pass a separate object for each item.

items/id integer

The item’s unique identifier.

sourceMaterials array optional

Contains any source material attached to the item set.

NOTE: If the item set contains multiple source materials, pass a separate object for each source material.

sourceMaterials/externalId string

The source material’s name in Surpass.

sourceMaterials/id integer

The source material’s unique identifier.

owner object optional

The item set owner’s information.

owner/id integer

The item set owner’s unique identifier.

comment string optional

Any comment left on the item in text format.

commentIsPrivate Boolean optional

Determines whether the comment is a private comment (only viewable by users with the Comment Manager permission) or not.

name string mandatory

The item set’s name.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new item set’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/1",
    "errors": null
}

Updating an item set

put /api/v2/ItemSet/{id}

Send a request to the endpoint to update a specific item set.

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.
content-type	header MANDATORY	`application/json` or `application/xml`	Determines data format of the request, which can be either JSON or XML.
content-length	header MANDATORY	`{number}`	Determines the number of characters passed in the body of the request, where `{number}` is a numerical figure. This is usually automatically calculated when the request is sent.
accept	header OPTIONAL	`application/json` or `application/xml`	Determines data format of the response, which can be either JSON or XML.
id	path MANDATORY	`/api/v2/ItemSet/{id}`	Update specified item set, where `{id}` is the item set’s unique identifier.

Sample request

At least one object must be updated in the request. The following request contains the minimum required request body to update an item set. Refer to the request body schema for all objects that can be updated.

{
    "name": "Item Set 2"
}

EXAMPLE: In this sample request, the item set is renamed to ‘Item Set 2’.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the updated item set’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/ItemSet/1",
    "errors": null
}

Deleting an item set

delete /api/v2/ItemSet/{id}

Send a request to the endpoint to delete a specific item set. No request body is required.

IMPORTANT: If the item set is not already in the subject’s recycle bin, the first request moves the item set into the subject’s recycle bin (the permanentlyDeleted property is false) and then the second request permanently deletes the item set (permanentlyDeleted is true).

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.

path

MANDATORY

/api/v2/ItemSet/{id}

Deletes specified item set, where {id} is the item set’s unique identifier.

Sample response

If successful, the HTTP status code will be 200 and the response body will confirm the item set has been deleted by returning a null id.

{
    "permanentlyDeleted": true,
    "id": null,
    "href": null,
    "errors": null,
    "serverTimeZone": null
}

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/ItemSet?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.

ItemSet API

In This Article

Listing item sets

Parameters

Sample response

Response schema

Retrieving item set information

Parameters

Sample response

Response schema

Creating an item set

Parameters

Sample request

Request body schema

Sample response

Updating an item set

Parameters

Sample request

Request body schema

Sample response

Deleting an item set

Parameters

Sample response

Error Codes

Further reading

About the site