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|
|Search and Filter||GET||https://...surpass.com/api/v2/ItemList?$filter=name eq 'Item List Name'|
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.
|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|
|The primary subject the list has been assigned to.
Users will need permission to this subject prior to seeing a list in the UI
|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|
|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|
|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|
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.
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.
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.
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:
You cannot DELETE subject master lists. To DELETE a subject master list, you must DELETE the subject itself.
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.