ItemList API
Item lists contain references to items that might exist across many different subjects. Item lists are used for LOFT/Adaptive tests and in Authoring, Review, and Standard Setting tasks.
The ItemList API resource is used to list, retrieve, create, update, and delete item lists.
This article explains what calls can be made to the Surpass API using the ItemList resource.
Import this API into your Postman Workspace
In This Article
Listing item lists
Send a request to the endpoint to retrieve a list of item lists. Refer to the available parameters to influence the response. No request body is required.
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. |
|
top |
query OPTIONAL |
/api/v2/ItemList?$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/ItemList?$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/ItemList?$filter={filter} {operator} {value} |
Filters results, searching either for an exact match or for the data to contain a defined value. For an exact match: {filter} is name, subject/id, subject/reference, {operator} is eq (equal to), and {value} is the string, integer or Boolean the filter query looks for an exact match for in the request. For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is one of name or reference, and {value} is the string or integer the filter query looks for the data to contain in the request. |
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": 147,
"top": 10,
"skip": 0,
"pageCount": 15,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/itemlist?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Geography Item List 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/1"
},
{
"id": 2,
"reference": "Geography Item List 2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/2"
},
{
"id": 3,
"reference": "Geography Item List 3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/3"
},
{
"id": 4,
"reference": "Geography Item List 4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/4"
},
{
"id": 5,
"reference": "Geography Item List 5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/5"
},
{
"id": 6,
"reference": "History Item List 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/6"
},
{
"id": 7,
"reference": "History Item List 2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/7"
},
{
"id": 8,
"reference": "History Item List 3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/8"
},
{
"id": 9,
"reference": "History Item List 4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/9"
},
{
"id": 10,
"reference": "History Item List 5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/10"
}
],
"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 lists there are in total.
top integer
Details number of item lists returned in the response.
skip integer
Details how many item lists were skipped to display those in the response.
pageCount integer
Details how many pages of item lists there are.
nextPageLink string
The endpoint to call the next page of item lists. If null, the response is the last page of item lists.
prevPageLink string
The endpoint to call the previous page of item lists. If null, the response is the first page of item lists.
response array
Contains the rest of the response.
id integer
The item list’s unique identifier.
reference string
The item list’s unique reference code.
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.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving item list information
Send a request to the endpoint to retrieve information for a specific item list using either its ID or reference. No request body is required.
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/ItemList/{id} |
Returns information for the specified item list, where {id} is the item list’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/ItemList?reference={reference} |
Returns information for the specified item list, where {reference} is the item list’s unique reference code. |
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": [
{
"name": "Geography Item List 1",
"subject": {
"id": 1,
"reference": "Subject1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": "Geography Subject 1"
},
"createdBy": {
"id": 1,
"reference": "User1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/User/1"
},
"dateCreated": "2020-07-30T09:59:50.3",
"publishable": false,
"isSubjectMasterList": false,
"isDeleted": false,
"items": [
{
"id": 1,
"type": "DragAndDrop",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Item/1",
"subject": {
"id": 1,
"reference": "Geography Subject 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
}
},
{
"id": 2,
"type": "MultipleChoice",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Item/2",
"subject": {
"id": 2,
"reference": "Geography Subject 2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/2",
"name": null
}
}
],
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/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 lists there are in total. This is null because the information retrieved is for a specific item list.
top integer
Details number of item lists returned in the response. This is null because the information retrieved is for a specific item list.
skip integer
Details how many item lists were skipped to display those in the response. This is null because the information retrieved is for a specific item list.
pageCount integer
Details how many pages of item lists there are. This is null because the information retrieved is for a specific item list.
nextPageLink string
The endpoint to call the next page of item lists. This is null because the information retrieved is for a specific item list.
prevPageLink string
The endpoint to call the previous page of item lists. This is null because the information retrieved is for a specific item list.
response array
Contains the rest of the response.
name string
The item list’s name.
subject object
Contains the subject that the item list is in.
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.
createdBy array
Contains the user who created the item list’s information.
createdBy/id integer
The user’s unique identifier.
createdBy/reference string
The user’s unique reference code.
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.
dateCreated string
The date the item list was created, in YYYY/MM/DD format.
publishable Boolean
If true, the item list can be published into external systems.
isSubjectMasterList Boolean
Determines whether the item list is a subject master list. A subject master list contains all items from its parent subject.
isDeleted Boolean
Determines whether the item list is in the subject’s item list recycle bin (true) or not (false).
items array
Contains the information of any items in the item list.
items/id integer
The item’s unique identifier.
items/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.
items/href string
The endpoint to call the item’s information, such as /api/v2/Item/{id} where {id} is the item’s unique identifier.
items/subject object
Contains the information for the subject that the item is in.
[/note]items/subject/id integer
The subject’s unique identifier.
items/subject/reference string
The subject’s unique reference code.
items/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.
items/subject/name string
The subject’s name.
id integer
The item list’s unique identifier.
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.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating an item list
Send a request to the endpoint to create an item list.
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 list.
{
"name": "Geography Item List 1",
"subject": {
"reference": "ItemList1"
},
"items": [
{
"id": 1
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string mandatory
The item list’s name.
subject object mandatory
Contains the subject that the item list is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
publishable Boolean optional
If true, the item list can be published into external systems. Defaults to true if omitted.
items array mandatory
Contains the information of any items in the item list.
items/id integer
The item’s unique identifier.
items/reference string
The item’s unique reference code.
reference string optional
The item list’s unique reference code.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new item list’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/1",
"errors": null,
"serverTimeZone": null
}Updating an item list
Send a request to the endpoint to update a specific item list.
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/ItemList/{id} |
Update specified item list, where {id} is the item list’s unique identifier. |
Sample request
At least one property must be updated in the request. The following request contains the minimum required request body to update an item list. Refer to the request body schema for all properties that can be updated.
{
"items": [
{
"id": 1
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string
The item list’s name.
publishable Boolean
If true, the item list can be published into external systems.
items array
Contains the information of any items in the item list.
items/id integer
The item’s unique identifier.
items/reference string
The item’s unique reference code.
reference string
The item list’s unique reference code.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated item list’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemList/1",
"errors": null,
"serverTimeZone": null
}Deleting an item list
Send a request to the endpoint to delete a specific item list. No request body is required.
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} |
Deletes specified item list, where {id} is the item list’s unique identifier. |
|
reference |
query OPTIONAL |
/api/v2/ItemList?reference={reference} |
Deletes specified item list, where {reference} is the item list’s unique reference code. |
|
permanent |
query OPTIONAL |
/api/v2/ItemList?permanent={Boolean} |
Permanently deletes specified item list. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the item list has been deleted by returning a null id.
{
"id": null,
"href": null,
"errors": null,
"serverTimeZone": null
}Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
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/ItemList?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
ItemListHasNoItems |
154 |
The item list cannot be created because it contains no items. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: