ItemTagValue API
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”.
Tags are made up of categorised containers called “tag groups” that contain individual tags called “tag values”. For example, a tag group called “difficulty” might have the following tag values: “Easy”, “Medium”, and “Hard”.
The ItemTagValue API is used to retrieve, assign, and delete item and tag value associations. For information on tag groups and tag values, read TagGroup API and TagValue API.
This article explains what calls can be made to the Surpass API using the ItemTagValue resource.
Import this API into your Postman Workspace
In This Article
Retrieving item and tag value association information
Send a request to the endpoint to retrieve information for a specific item and tag value association using its ID. 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 MANDATORY |
/api/v2/ItemTagValue/{id} |
Returns information for the specified item and tag value association, where {id} is the item and tag value’s unique identifier. |
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": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemTagValue/1",
"tagValue": {
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/1"
},
"item": {
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/Item/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 and tag value associations there are in total. This is null because the information retrieved is for a specific item and tag value association.
top integer
Details number of item and tag value associations returned in the response. This is null because the information retrieved is for a specific item and tag value association.
skip integer
Details how many item and tag value associations were skipped to display those in the response. This is null because the information retrieved is for a specific item and tag value association.
pageCount integer
Details how many pages of item and tag value associations there are. This is null because the information retrieved is for a specific item and tag value association.
nextPageLink string
The endpoint to call the next page of item and tag value associations. This is null because the information retrieved is for a specific item and tag value association.
prevPageLink string
The endpoint to call the previous page of item and tag value associations. This is null because the information retrieved is for a specific item and tag value association.
response array
Contains the rest of the response.
id integer
The item and tag value association’s unique identifier.
href string
The endpoint to call the item and tag value association’s information, such as /api/v2/ItemTagValue/{id} where {id} is the item and tag value’s unique identifier.
tagValue object
The tag value’s information.
tagValue/id integer
The tag value’s unique identifier.
tagValue/href string
The endpoint to call the tag value’s information, such as /api/v2/TagValue/{id} where {id} is the tag value’s unique identifier.
item object
The item’s information.
item/id integer
The item’s unique identifier.
item/href string
The endpoint to call the item’s information, such as /api/v2/Item/{id} where {id} is the item’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Assigning a tag value to an item
Send a request to the endpoint to assign a tag value to an item.
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 and tag value association.
{
"item": {
"id": 1
},
"tagValue": {
"Id": 1
},
"tagGroup": {
"Id": 1
}
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
item object mandatory
The item’s information.
item/id integer
The item’s unique identifier.
item/reference string
The item’s unique reference code.
item/href string
The endpoint to call the item’s information, such as /api/v2/Item/{id} where {id} is the item’s unique identifier.
tagValue object mandatory
The tag value’s information.
tagValue/Id integer
The tag value’s unique identifier.
tagValue/Text string
The tag value’s text.
tagValue/Number integer
The tag value’s number, in decimal format (for example, 2.0).
tagGroup object mandatory
The information of the tag group that contains the tag group.
tagGroup/id integer
The tag group’s unique identifier.
mark integer optional
The mark for the tag value if the tag group is Learning Outcomes and marked learning outcomes are enabled.
collection object optional
Contains tag collection information if assigning a tag collection to an item. A tag collection lets users group tag values from across different tag groups.
collection/subCollection object
Contains subcollection information.
collection/subCollection/collectionGroup object
Contains the subcollection’s subcollection group information.
collection/subCollection/collectionGroup/id integer
The subcollection’s unique identifier.
collection/subCollection/collectionGroup/reference integer
The subcollection’s unique reference code.
collection/isCurrent Boolean
Determines whether the subcollection is marked as the latest subcollection.
collection/collectionGroup object
Contains the tag collection’s tag collection group information.
collection/collectionGroup/id integer
The tag collection group’s unique identifier.
collection/collectionGroup/reference integer
The tag collection group’s unique reference code.
collection/name string
The tag collection’s name.
collection/reference string
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 new item and tag value association’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/ItemTagValue/1",
"errors": null
}Deleting an item and tag value association
Send a request to the endpoint to delete a specific item and tag value association.
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. |
Sample request
The following request contains the minimum required request body to delete an item and tag value association. Refer to the request body schema for all the objects required to delete an item and tag value association.
{
"item": {
"id": 1
},
"tagValue": {
"Id": 1
},
"tagGroup": {
"Id": 1
}
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
item object mandatory
The item’s information.
item/id integer
The item’s unique identifier.
tagValue object mandatory
The tag value’s information.
tagValue/id integer
The tag value’s unique identifier.
tagGroup object mandatory
The information of the tag group that contains the tag group.
tagGroup/id integer
The tag group’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the item and tag value association 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. |
|
FailedToCreateTagCategory |
174 |
There is an issue with creating the tag category |
|
TagCategoryDoesNotExist |
176 |
There is an issue with deleting the tag category. |
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: