Item List Resource

In Surpass we offer the ability to search for items across subjects in Item Authoring, then users with the relevant permission can save these searches as lists so these items can be distributed as required to Item Authors. Authors can select items and will be re-directed to the Edit item page in Item Authoring.

The Item List Resource in the Surpass refers directly to the list properties and the saved items within the list rather than the search parameters used to create the list. We offer the ability to export, search, import and remove lists in Surpass via the API.

 
Item List Resource 

Below we have listed the operations, http verbs and an example URL for the ItemList resource within the Surpass API.
Operation HTTP Verb Example URL
Read (Individual) GET https://...surpass.com/api/v2/ItemList/1
https://...surpass.com/api/v2/ItemList?reference={ItemListRef}
Search and Filter GET https://...surpass.com/api/v2/ItemList?$filter=name eq 'Item List Name'
Create POST https://...surpass.com/api/v2/ItemList/
Update PUT https://...surpass.com/api/v2/ItemList/{ID}
Remove DELETE https://...surpass.com/api/v2/ItemList/1
Properties for the Item List Resource 


Within the table below we have provided all of the attributes included in the ItemList resource. This includes the attribute name, data type, if the attribute is orderable when requesting the GET method, if the attribute is available to filter when requesting the GET method, and if the attribute is mandatory when creating a candidate. Remember that if an attribute is not mandatory it can be omitted from the body of the POST request.    
Property Name Type Description Filter
(GET)
Mandatory
(POST)
Default Value
(POST)
id int The unique id of the Item List. Unable to POST. n/a n/a
reference string The item list reference x n/a
href string The URL to request the individual item list. Unable to POST. n/a n/a
name string The name of the item list x x n/a
subject resource
(object)
The primary subject the list has been assigned to.
Users will need permission to this subject prior to seeing a list in the UI
x x n/a
subject / id int The unique id of the subject assigned to the list n/a
subject / reference string The unique reference of the subject assigned to the list n/a
subject / href string The URL to request the individual subject n/a
createdBy resource
(object)
The user that created the list. This relates to the User resource in the Surpass API.
Unable to POST.
n/a Authenticating API User
createdBy / id int The unique ID of the user that created the list n/a n/a
createdBy / reference string The username of the user that created the list n/a n/a
createdBy / href string The URL to request the individual user n/a n/a
dateCreated dateTime The date/time the item list was created. Unable to POST. n/a Request Time
isBroadcasted boolean This flag identifies if the item list has been broadcasted where a notification will be sent to an external system. Please contact BTL if this is something you require. false
items resource
(collection)
All items contained within this item list will be returned in this collection x n/a
items / id int The unique id of each item within the item list. n/a
items / href string The URL to request each item in the item list n/a
items / subject resource The subject the item belongs to. n/a
items / subject / id int The ID of the subject the item belongs to. n/a
items / subject / reference string The reference of the subject the item belongs to. n/a
items / subject / href string The URL to GET the subject that the item belongs to. n/a
GET Request and Return

The GET ItemList 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 ItemList resource.

Example GET request & response (JSON)

Example GET request & response (XML)

POST Request and Return

The POST ItemList method requires the attributes listed above to be submitted as part of the body of the 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.  

Depending on how the request was submitted the response will be returned in either JSON or XML format. If the call was unsuccessful then you will receive an error message.

Example POST request & response (JSON)

Example POST request & response (XML)

PUT Request and Return  

PUT requests should reference the ID of the item list you would like to update as part of the request URL. 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 properties will be unchanged.

EXAMPLE PUT request & response (JSON)

EXAMPLE PUT request & response (XML)

DELETE Request and Return

DELETE requests should use the ID or reference of the ItemList you want to delete. Successful requests will return a status of 200 and will return the base resource with all values set to null. An example request has been provided below:

DELETE https://...surpass.com/api/v2/ItemList/1

You cannot DELETE subject master lists. To DELETE a subject master list, you must DELETE the subject itself.

Required Permissions

To successfully call the ItemList methods, the user specified in the header of the request must have the 'Manage Item Lists' permission in Surpass. 

Only users with the 'Subject Master Lists' permission can access the GET and PUT methods for a subject master list.

Feedback and Knowledge Base