ItemSet Resource

When authoring items in Surpass, it is possible to group them into Item Sets. Items within a set are those that are presented within the same test; such as items that refer to the same case study information or are required to answer the next item. This should not be confused with grouping, which is the ability to stack items in test delivery so they appear to the candidate as one page. When selecting an item for a test form that is contained within an Item Set it will also add all items within the set that have a live status.  

Item Set Resource 

Below we have listed the operations, HTTP verbs and an example URL for the Item Set resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/ItemSet/
Filter GET https://...surpass.com/api/v2/ItemSet?$filter=name,eq ‘Item Set 1’
Read (Individual by ID) GET https://...surpass.com/api/v2/ItemSet/1
Create POST https://...surpass.com/api/v2/ItemSet/
Update PUT https://...surpass.com/api/v2/ItemSet/1
Remove DELETE https://...surpass.com/api/v2/ItemSet/1
Properties for the Item Set Resource

Within the table below we have provided all of the attributes included in the Item Set resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.
Property Name Type Description Default Value Filterable (GET) Mandatory (POST)
subject object The subject that the Item Set belongs to. n/a x x
subject / id int The id of the subject the Item Set belongs to. x
subject / reference string The reference of the subject the Item Set belongs to. x
subject / href string The Request URL for the subject the Item Set is part of. n/a n/a n/a
parentFolderId int The id of the parent folder the Item Set belongs to. root folder x
position int The position of the folder within the parent folder. 0
name string The name of the Item Set. n/a x
items collection A collection of items within the Item Set. n/a
items / type enumeration The question type of the item within the Item Set.
items / id int The id of the item within the Item Set.
items / href string The request URL of the item within the Item Set.
id int The unique id of the Item Set. n/a n/a
href string The request URL of the Item Set. n/a n/a
GET Request and Return

The GET Item set resource can be called directly by browsing to the URL, any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the Item Set resource.

Example GET request & response (JSON)
Example GET request & response (XML)


POST Request and Return 

The POST Folder method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format. The content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.
  • If "parentFolderId" is omitted this will be created in the root directory. Subject and Name are mandatory.
  • "position" refers to the position of the folder in the parent folder. If a number is supplied that is higher than the number of folders/items the folder will be placed last. 
  • 0 refers to the root directory when supplied in the parent folder id property and also indicates the first position when supplying position property as part of the POST or PUT request.

PUT Request and Return

PUT Requests should reference the ID of the resource. The properties being updated should be included in the body of the request and can be sent in either JSON or XML format. All properties are optional within the PUT request so any omitted proprieties will be unchanged. The "Authorization" header will also be required in the request for it to be successful.

The body of the request should be formed in the same way as the POST request and the response also returns the same information. An example of this can be found in the “POST Request and Return” section above. The only differences between the POST and PUT requests is that the ID is required as part of the URL, all fields are optional and Subject cannot be supplied in the PUT request.


Required Permissions

To successfully call the Item Set methods, the user specified in the header of the request must have the "Item Writer", “Item Reviewer” or “Item Publisher” permission in Surpass depending on the status of the items within the set.

Feedback and Knowledge Base