ItemSet API

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"
}

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/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": [],
            "language": {
                "name": "English (UK)",
                "code": "en"
            },
            "languageVariants": [],
            "status": "Reviewed",
            "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

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

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.

language object

If item language variants are enabled, contains the information related to the item set’s language (the default language of the item set).

NOTE: The available languages for all item language variants in a subject are those enabled in Site Settings. For more information about site settings, read ‘About Language Variants settings‘ in About Site Settings options.

language/name string

The name of the language.

language/code enumeration

The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.

languageVariants array

If item language variants are enabled, contains the language variant(s) information.

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

languageVariants/deleted Boolean

Determines whether the language variant has been deleted. Deleted language variants can be stored or permanently deleted.

languageVariants/href string

The endpoint to call the language variant’s information, such as /api/v2/ItemSet/{id}/LanguageVariant/{languageCode} where {id} is the item set’s unique identifier and {languageCode} is the language variant’s ISO code.

languageVariants/name string

The name of the language.

languageVariants/code enumeration

The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.

status enumeration

The item set’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Custom workflow statuses can also be created and assigned to items and item sets.

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.

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.
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.

language object mandatory

If item language variants are enabled, contains the information related to the item set’s language (the default language of the item set).

NOTE: The available languages for all item language variants in a subject are those enabled in Site Settings. For more information about site settings, read ‘About Language Variants settings‘ in About Site Settings options.

language/code enumeration

The language’s ISO code. The available language codes are amh, ar, arm, pob, bul, mya, zh, zho, hrv, ces, dan, nl, en-int, en, us, est, per, tgl, fin, frc, ga, gle, glg, ge, gre, heb, hun, ind, ita, jpn, kk, khm, kor, lao, la, lav, lit, mlt, mon, nep, no, pol, por, iir, ron, rus, smo, slk, slv, som, sp, es-int, lac, es-pa, es-pr, swe, tha, tur, ukr, vie, and we.

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

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

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.

status enumeration optional

The item set’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Custom workflow statuses can also be created and assigned to items and item sets.

Defaults to Draft if omitted.

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
}

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.
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}`	Updates 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’.

Request body schema

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

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.

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.

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, 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

If using the Nuxeo media repository: the media’s external reference. For more information about Nuxeo, read ‘About Media settings’ in About Site Settings options.

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.

comment string

Any comment left on the item in text format.

commentIsPrivate Boolean

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

status enumeration

The item set’s workflow status. The default workflow statuses are Draft, To Review, Reviewed, Live, and Withdrawn. Custom workflow statuses can also be created and assigned to items and item sets.

Defaults to Draft if omitted.

name string

The item set’s name.

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
}

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

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
}

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.

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