TagCollection OAPI
In Surpass, you can attach metadata (known as “tags”) to items and then use these tags to organise items when authoring content, creating tests, and viewing results. Tags are made up of “tag groups” and “tag values”.
A “tag collection” lets you categorise tag groups and tag values, which is useful for comparing data across multiple tag groups. Tag collections are subject-specific and are contained in “tag collection groups”. Read TagCollectionGroup OAPI for more information on tag collection groups.
The TagCollection OAPI resource is used to list, retrieve, create, update, and delete tag collections. You can also update individual tag values in a specified tag collection and the order of tag collections within the tag collection group.
This article explains what calls can be made to the Surpass OAPI using the TagCollection resource.
Import this API into your Postman Workspace
In This Article
Listing tag collections
Send a request to the endpoint to retrieve a list of tag collections. 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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
fieldsNames |
query OPTIONAL |
/oapi/TagCollection?fieldsNames={fieldsNames} |
Includes additional properties in the response not returned as standard, where {fieldsNames} is one of the following properties returned when retrieving information for a specific item: tagGroups. |
|
filter |
query OPTIONAL |
/oapi/TagCollection?filter={filter} {operator} {value} |
Filters results, searching for an exact match or for the data to contain a defined value. For an exact match: {filter} is one of id, reference, name, order, isCurrent, collectionGroup.id, collectionGroup.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 greater than query: {filter} is id, order, collectionGroup.id; {operator} is ge (greater than); and {value} is the integer the filter looks for more than in the request. For a less than query: {filter} is id, order, collectionGroup.id; {operator} is le (less than); and {value} is the integer the filter looks for less than in the request. For a contains query: {filter} is one of reference, name, collectionGroup.reference; {operator} is contains; and {value} is the string the filter query looks for an exact match for in the request. |
|
filterGrouping |
query OPTIONAL |
/oapi/TagCollection?filter={filter} {operator} {value}&filter={filter} {operator} {value}&filterGrouping={integer} {operator} {integer} |
Used to create different Boolean combinations when multiple properties are joined within a filter query parameter. See filter above. Each {integer} represents a respective filter starting at 0, which are then combined using an AND or OR Boolean {operator}.
EXAMPLE: The endpoint /oapi/TagCollection?filter=id le 10&filter=isCurrent eq true&filterGrouping=0 OR 1 would return both tag collection groups with a unique identifier less than 10 (0) and tag collections set as the latest tag collection (1).
TIP: More than two filter parameters can be combined, for example you might group three filters as follows: 0 AND 1 OR 2.
|
|
orderBy |
query OPTIONAL |
/oapi/TagCollection?orderBy=fieldName={fieldName} |
Determines order of results, where {fieldName} is id, reference, name, order, or isCurrent. |
|
take |
query OPTIONAL |
/oapi/TagCollection?take={take} |
Defines number of responses to return when paging a response, where {take} is a number between 1 and 100. |
|
skip |
query OPTIONAL |
/oapi/TagCollection?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. |
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": 285,
"top": 5,
"skip": 0,
"totalPages": 57,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/TagCollection?Skip=5&Take=5",
"previousPageLink": null,
"results": [
{
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"id": 1,
"reference": "TC1",
"name": "Tag Collection 1",
"order": 0,
"isCurrent": true,
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"subCollections": []
},
{
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"id": 2,
"reference": "TC2",
"name": "Tag Collection 2",
"order": 1,
"isCurrent": false,
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"subCollections": []
},
{
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"id": 2,
"reference": "TC3",
"name": "Tag Collection 3",
"order": 2,
"isCurrent": false,
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"subCollections": []
},
{
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"id": 4,
"reference": "TC4",
"name": "Tag Collection 4",
"order": 3,
"isCurrent": false,
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"subCollections": []
},
{
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"id": 5,
"reference": "TC5",
"name": "Tag Collection 5",
"order": 4,
"isCurrent": false,
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"subCollections": []
}
],
"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 tag collections there are in total.
top integer
Details number of tag collections returned in the response.
skip integer
Details how many tag collections were skipped to display those in the response.
totalPages integer
Details how many pages of tag collections there are.
nextPageLink string
The endpoint to call the next page of tag collections. If null, the response is the last page of tag collections.
previousPageLink string
The endpoint to call the previous page of tag collections. If null, the response is the first page of tag collections.
results array
Contains the rest of the response.
item object
Contains the information of the item the tag collection is assigned to.
item/id integer
The item’s unique identifier.
item/reference string
The item’s unique reference code.
item/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.
item/name string
The item’s name.
item/position integer
item/href string
The endpoint to call the item’s information, such as /oapi/Item/{id} where {id} is the item’s unique identifier.
id integer
The tag collection’s unique identifier.
reference string
The tag collection’s unique reference code.
name string
The tag collection’s name.
order integer
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
isCurrent Boolean
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.
collectionGroup object
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
collectionGroup/href string
The endpoint to call the tag collection group’s information, such as /oapi/TagCollectionGroup/{id} where {id} is the tag collection group’s unique identifier.
subCollections array
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/id integer
The subcollection’s unique identifier.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup object
Contains the tag group’s information.
subCollections/tagGroups/tagGroup/id integer
The tag group’s unique identifier.
subCollections/tagGroups/tagGroup/name string
The tag group’s unique reference code, which is also its name.
subCollections/tagGroups/tagGroup/href string
The endpoint to call the tag group’s information, such as /api/v2/TagGroup/{id} where {id} is the tag group’s unique identifier.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/collectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/collectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/collectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
subCollections/collectionGroup/href string
The endpoint to call the subcollection group’s information, such as /oapi/TagCollectionGroup/{id} where {id} is the subcollection group’s unique identifier.
subCollections/isCurrent Boolean
Determines whether the subcollection is the latest subcollection (true). Only the latest tag values can be returned when searching for items in Item Search.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving tag collection information
Send a request to the endpoint to retrieve information for a specific tag collection group using 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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
id |
query OPTIONAL |
/oapi/TagCollection/GetByIdReference?id={id} |
Returns information for the specified tag collection, where {id} is the tag collection’s unique identifier. |
|
reference |
query OPTIONAL |
/oapi/TagCollection/GetByIdReference?reference={reference} |
Returns information for the specified tag collection, where {reference} is the tag collection’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.
{
"response": {
"id": 1,
"reference": "TC1",
"tagGroups": [
{
"tagGroup": {
"id": 1,
"name": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
"tagValue": "Tag Value 1"
}
],
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"isCurrent": false,
"name": "Tag Collection 1",
"order": 1,
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"subCollections": []
},
"serverTimeZone": "GMT Standard Time"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
response object
Contains the rest of the response.
id integer
The tag collection’s unique identifier.
reference string
The tag collection’s unique reference code.
tagGroups/tagGroup object
Contains information for the tag collection’s tag groups and values.
tagGroups/tagGroup object
Contains the tag group’s information.
tagGroups/tagGroup/id integer
The tag group’s unique identifier.
tagGroups/tagGroup/name string
The tag group’s unique reference code, which is also its name.
tagGroups/tagGroup/href string
The endpoint to call the tag group’s information, such as /api/v2/TagGroup/{id} where {id} is the tag group’s unique identifier.
tagGroups/tagValue string
The name of the tag value.
collectionGroup object
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
collectionGroup/href string
The endpoint to call the tag collection group’s information, such as /oapi/TagCollectionGroup/{id} where {id} is the tag collection group’s unique identifier.
isCurrent Boolean
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.
name string
The tag collection’s name.
order integer
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
item object
Contains the information of the item the tag collection is assigned to.
item/id integer
The item’s unique identifier.
item/reference string
The item’s unique reference code.
item/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.
item/name string
The item’s name.
item/position integer
item/href string
The endpoint to call the item’s information, such as /oapi/Item/{id} where {id} is the item’s unique identifier.
subCollections array
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/id integer
The subcollection’s unique identifier.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup object
Contains the tag group’s information.
subCollections/tagGroups/tagGroup/id integer
The tag group’s unique identifier.
subCollections/tagGroups/tagGroup/name string
The tag group’s unique reference code, which is also its name.
subCollections/tagGroups/tagGroup/href string
The endpoint to call the tag group’s information, such as /api/v2/TagGroup/{id} where {id} is the tag group’s unique identifier.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/collectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/collectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/collectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
subCollections/collectionGroup/href string
The endpoint to call the subcollection group’s information, such as /oapi/TagCollectionGroup/{id} where {id} is the subcollection group’s unique identifier.
subCollections/isCurrent Boolean
Determines whether the subcollection is the latest subcollection (true). Only the latest tag values can be returned when searching for items in Item Search.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a tag collection
Send a request to the endpoint to create a tag collection.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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 |
Determines data format of the response (JSON). |
Sample request
The following request contains the minimum required request body to create a tag collection.
{
"tagGroups": [
{
"tagGroup": "Tag Group 1",
"tagValue": "Tag Value 1"
}
],
"order": 0,
"reference": "TC1",
"itemId": 1,
"collectionGroup": {
"id": 1
}
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
tagGroups array mandatory
Contains information for the tag collection’s tag groups and values.
tagGroups/tagGroup string
The name of the tag group.
tagGroups/tagValue string
The name of the tag value.
name string optional
The tag collection’s name. If omitted, the tag collection’s unique reference code is used as its name instead.
order integer optional
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
reference string mandatory
The tag collection’s unique reference code.
itemId integer mandatory
The item’s unique identifier.
collectionGroup object mandatory
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
isCurrent Boolean optional
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search. Defaults to false if omitted.
subCollections array optional
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup string
The name of the tag group.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/subCollectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/subCollectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/subCollectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag collection’s details.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}Creating multiple tag collections
Send a request to the endpoint to create multiple tag collections.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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 |
Determines data format of the response (JSON). |
Sample request
The following request contains the minimum required request body to create multiple tag collections.
[
{
"tagGroups": [
{
"tagGroup": "Tag Group 1",
"tagValue": "Tag Value 1"
}
],
"reference": "TC1",
"itemId": 1,
"collectionGroup": {
"id": 1
}
},
{
"tagGroups": [
{
"tagGroup": "Tag Group 2",
"tagValue": "Tag Value 2"
}
],
"reference": "TC2",
"itemId": 1,
"collectionGroup": {
"id": 1
}
}
]Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
tagGroups array mandatory
Contains information for the tag collection’s tag groups and values.
tagGroups/tagGroup string
The name of the tag group.
tagGroups/tagValue string
The name of the tag value.
name string optional
The tag collection’s name. If omitted, the tag collection’s unique reference code is used as its name instead.
order integer optional
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
reference string mandatory
The tag collection’s unique reference code.
itemId integer mandatory
The item’s unique identifier.
collectionGroup object mandatory
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
isCurrent Boolean optional
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search. Defaults to false if omitted.
subCollections array optional
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup string
The name of the tag group.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/subCollectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/subCollectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/subCollectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag collections’ details. The data properties contain the tag collection’s unique identifier.
{
"response": [
{
"data": 1,
"errors": []
},
{
"data": 2,
"errors": []
}
],
"serverTimeZone": "GMT Standard Time"
}Updating a tag collection
Send a request to the endpoint to update a tag collection.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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. |
|
id |
query OPTIONAL |
/oapi/TagCollection?id={id} |
Updates the specified tag collection, where {id} is the tag collection’s unique identifier. |
|
reference |
query OPTIONAL |
/oapi/TagCollection?reference={reference} |
Updates the specified tag collection, where {reference} is the tag collection’s unique reference code. |
Sample request
The following request contains the minimum required request body to update a tag collection.
{
"name": "Tag Collection 2"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
tagGroups array
Contains information for the tag collection’s tag groups and values.
tagGroups/tagGroup string
The name of the tag group.
tagGroups/tagValue string
The name of the tag value.
name string
The tag collection’s name.
order integer
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
collectionGroup object
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
isCurrent Boolean
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.
subCollections array
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup string
The name of the tag group.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/subCollectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/subCollectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/subCollectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated tag collection’s details.
{
"response": {
"id": 1,
"reference": "TC1",
"tagGroups": [
{
"tagGroup": {
"id": 1,
"name": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
"tagValue": "Tag Value 1"
}
],
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"isCurrent": false,
"name": "Tag Collection 2",
"order": 1,
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"subCollections": []
},
"serverTimeZone": "GMT Standard Time"
}Updating multiple tag collections
Send a request to the endpoint to update multiple tag collections. Each tag collection’s id or reference is specified in the request body.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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. |
Sample request
The following request contains the minimum required request body to update multiple tag collections.
[
{
"id": 1,
"resource": {
"name": "Tag Collection 2"
}
},
{
"id": 2,
"resource": {
"name": "Tag Collection 1"
}
}
]Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
id integer
The tag collection’s unique identifier.
reference string
The tag collection’s unique reference code.
resource object mandatory
Contains the tag collection’s information.
resource/name string
The tag collection’s name.
tagGroups array
Contains information for the tag collection’s tag groups and values.
tagGroups/tagGroup string
The name of the tag group.
tagGroups/tagValue string
The name of the tag value.
name string
The tag collection’s name.
order integer
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
collectionGroup object
Contains the tag collection group’s information.
collectionGroup/id integer
The tag collection group’s unique identifier.
collectionGroup/reference string
The tag collection group’s unique reference code, which is also its name.
isCurrent Boolean
Determines whether the tag collection is the latest tag collection (true). Only the latest tag values can be returned when searching for items in Item Search.
subCollections array
Contains the information of any subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/tagGroups object
Contains information for the subcollection’s tag groups and values.
subCollections/tagGroups/tagGroup string
The name of the tag group.
subCollections/tagGroups/tagValue string
The name of the tag value.
subCollections/name string
The subcollection’s name.
subCollections/order integer
The subcollection’s position within the subcollection group. Subcollections are ordered from the highest to the lowest order property.
subCollections/reference string
The subcollection’s unique reference code.
subCollections/subCollectionGroup object
Contains information for the subcollection’s subcollection group.
subCollections/subCollectionGroup/id integer
The subcollection group’s unique identifier.
subCollections/subCollectionGroup/reference string
The subcollection group’s unique reference code, which is also its name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated tag collections’ details.
{
"response": [
{
"data": {
"id": 1,
"reference": "TC1",
"tagGroups": [
{
"tagGroup": {
"id": 1,
"name": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
"tagValue": "Tag Value 1"
}
],
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"isCurrent": false,
"name": "Tag Collection 2",
"order": 1,
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"subCollections": []
},
"errors": []
},
{
"data": {
"id": 2,
"reference": "TC2",
"tagGroups": [
{
"tagGroup": {
"id": 1,
"name": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
"tagValue": "Tag Value 1"
}
],
"collectionGroup": {
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/oapi/TagCollectionGroup/1"
},
"isCurrent": false,
"name": "Tag Collection 1",
"order": 1,
"item": {
"id": 1,
"reference": "MCQ1",
"type": "MultipleChoice",
"name": "Geography MCQ1",
"position": 0,
"href": "https://{your Surpass instance}.surpass.com/oapi/Item/1"
},
"subCollections": []
},
"errors": []
}
],
"serverTimeZone": "GMT Standard Time"
}Updating a tag value
Send a request to the endpoint to update a specific tag value. No request body is required; each tag collection, tag group, and the updated tag value are included in the request endpoint as query parameters.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
accept |
header OPTIONAL |
application/json or application/xml |
Determines data format of the response, which can be either JSON or XML. |
|
collectionReference |
query MANDATORY |
/oapi/TagCollection/SingleValue?collectionReference={collectionReference} |
Updates tag value for the specified tag collection, where {collectionReference} is the tag collection’s unique reference code. |
|
tagGroup |
query MANDATORY |
/oapi/TagCollection/SingleValue?tagGroup={tagGroup} |
Updates tag value for the specified tag group, where {tagGroup} is the tag group’s name. |
|
tagValue |
query MANDATORY |
/oapi/TagCollection/SingleValue?tagValue={tagValue} |
Updates tag value, where {tagValue} is the updated tag value’s name. |
|
subCollectionReference |
query OPTIONAL |
/oapi/TagCollection/SingleValue?subCollectionReference={subCollectionReference} |
Updates tag value for the specified subcollection, where {subCollectionReference} is the subcollection’s unique reference code. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the tag value has been updated.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}Updating the order of tag collections
Send a request to the endpoint to update the position of tag collections within the tag collection group. Tag collections are ordered from the highest to the lowest order property. Each tag collection’s id or reference is specified in the request body.
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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
content-type |
header MANDATORY |
application/json |
Determines data format of the request (JSON). |
|
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. |
Sample request
The following request contains the minimum required request body to update the position of a single tag collection in its tag collection group.
{
"collections": [
{
"id": 1,
"order": 2
}
]
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
collections array
Contains the tag collection’s information.
collections/id integer
The tag collection’s unique identifier.
collections/reference string
The tag collection’s unique reference code.
collections/order integer
The tag collection’s position within the tag collection group. Tag collections are ordered from the highest to the lowest order property.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated tag collection’s details.
{
"response": [
{
"errorCode": 0,
"description": {
"id": 1,
"reference": null,
"message": null
}
}
],
"serverTimeZone": "GMT Standard Time"
}Deleting a tag collection
Send a request to the endpoint to delete a specific tag collection. 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 OPTIONAL |
Basic {credentials} |
Basic authentication details must be passed to authorise the user’s request, where {credentials} is a Base64 encoded username:password string. |
|
authorization |
header OPTIONAL |
Bearer {token} |
A bearer token must be passed to authorise the user’s request, where {token} is a JWT (JSON web token). |
|
accept |
header OPTIONAL |
application/json |
Determines data format of the response (JSON). |
|
id |
query MANDATORY |
/oapi/TagCollection?id={id} |
Deletes specified tag collection, where {id} is the tag collection’s unique identifier. |
Error Codes
Refer to the following table for information on error codes that may be encountered when using this resource.
|
Code |
Description |
|---|---|
|
400 |
Indicates one of the following issues:
|
|
401 |
The request has been sent by an unauthorised user. |
|
403 |
Tag collection cannot be accessed. |
|
404 |
Tag collection does not exist. |
Further reading
Read the following articles to learn how to get started with the Surpass OAPI or more about similar APIs: