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{ItemListRef}
Search and Filter GET$filter=name eq 'Item List Name'
Create POST
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
Default Value
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
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
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
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
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)

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:


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. 

Feedback and Knowledge Base