TagHierarchy 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”.
Tag groups can be further categorised into tag hierarchies. Item authors can select and assign tag values to items from a pre-defined tag hierarchy. You can create tag hierarchies in the Subjects screen of Setup. Tag hierarchies are subject-specific.
The TagHierarchy API resource is used to list, retrieve, and create tag hierarchies.
This article explains what calls can be made to the Surpass API using the TagHierarchy resource.
Import this API into your Postman Workspace
In This Article
Listing tag hierarchies
Send a request to the endpoint to retrieve a list of tag hierarchies. 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/TagHierarchy?$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/TagHierarchy?$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/TagHierarchy?$filter={filter} {operator} {value} |
Filters results, searching for the data to contain a defined value. For a contains query: {filter} is contains({attribute}, '{value}'), where {attribute} is name; and {value} is the string the filter query looks for the data to contain in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/TagHierarchy?$orderBy={attribute} |
Determines order of results, where {attribute} is name. |
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": 5,
"top": 10,
"skip": 0,
"pageCount": 1,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"id": 1,
"name": "Tag Hierarchy 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/1"
},
{
"id": 2,
"name": "Tag Hierarchy 2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/2"
},
{
"id": 3,
"name": "Tag Hierarchy 3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/3"
},
{
"id": 4,
"name": "Tag Hierarchy 4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/4"
},
{
"id": 5,
"name": "Tag Hierarchy 5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/5"
}
],
"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 tag hierarchies there are in total.
top integer
Details number of tag hierarchies returned in the response.
skip integer
Details how many tag hierarchies were skipped to display those in the response.
pageCount integer
Details how many pages of tag hierarchies there are.
nextPageLink string
The endpoint to call the next page of tag hierarchies. If null, the response is the last page of tag hierarchies.
prevPageLink string
The endpoint to call the previous page of tag hierarchies. If null, the response is the first page of tag hierarchies.
response array
Contains the rest of the response.
id integer
The tag hierarchy’s unique identifier.
name string
The name of the tag hierarchy.
href string
The endpoint to call the tag hierarchy’s information, such as /api/v2/TagHierarchy/{id} where {id} is the tag hierarchy’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 tag hierarchy information
Send a request to the endpoint to retrieve information for a specific tag hierarchy 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 OPTIONAL |
/api/v2/TagHierarchy/{id} |
Returns information for the specified tag hierarchy, where {id} is the tag hierarchy’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": [
{
"subject": {
"id": 1,
"reference": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1"
},
"id": 1,
"name": "Tag Hierarchy 1",
"shortCodesEnabled": true,
"contentCodeTagGroupName": "Combined Shortcode Tag Group",
"contentCodeTagTypeId": 4,
"contentCodeTagGroupHref": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/4",
"isPublished": true,
"tagHierarchyGroups": [
{
"id": 1,
"name": "Tag Group 1",
"subjectTagTypeId": 1,
"tagGroupHref": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1",
"nodes": [
{
"id": 1,
"name": "Tag Value 1.0",
"shortCode": "1",
"parentNodeId": null,
"subjectTagValueId": 1,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/1",
"contentCode": "1",
"contentCodeTagValueId": 16,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/16"
},
{
"id": 2,
"name": "Tag Value 2.0",
"shortCode": "2",
"parentNodeId": null,
"subjectTagValueId": 2,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/2",
"contentCode": "2",
"contentCodeTagValueId": 17,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/17"
},
{
"id": 3,
"name": "Tag Value 3.0",
"shortCode": "3",
"parentNodeId": null,
"subjectTagValueId": 3,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/3",
"contentCode": "3",
"contentCodeTagValueId": 18,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/18"
}
]
},
{
"id": 2,
"name": "Tag Group 2",
"subjectTagTypeId": 2,
"tagGroupHref": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/2",
"nodes": [
{
"id": 4,
"name": "Tag Value 1.1",
"shortCode": "1.1",
"parentNodeId": 1,
"subjectTagValueId": 4,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/4",
"contentCode": "1.1.1",
"contentCodeTagValueId": 19,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/19"
},
{
"id": 5,
"name": "Tag Value 1.2",
"shortCode": "1.2",
"parentNodeId": 1,
"subjectTagValueId": 5,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/5",
"contentCode": "1.1.2",
"contentCodeTagValueId": 20,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/20"
},
{
"id": 6,
"name": "Tag Value 1.3",
"shortCode": "1.3",
"parentNodeId": 1,
"subjectTagValueId": 6,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/6",
"contentCode": "1.1.3",
"contentCodeTagValueId": 21,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/21"
},
{
"id": 7,
"name": "Tag Value 2.1",
"shortCode": "2.1",
"parentNodeId": 2,
"subjectTagValueId": 7,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/7",
"contentCode": "2.2.1",
"contentCodeTagValueId": 22,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/22"
},
{
"id": 8,
"name": "Tag Value 2.2",
"shortCode": "2.2",
"parentNodeId": 2,
"subjectTagValueId": 8,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/8",
"contentCode": "2.2.2",
"contentCodeTagValueId": 23,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/23"
},
{
"id": 9,
"name": "Tag Value 3.1",
"shortCode": "3.1",
"parentNodeId": 3,
"subjectTagValueId": 9,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/9",
"contentCode": "3.3.1",
"contentCodeTagValueId": 24,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/24"
}
]
},
{
"id": 3,
"name": "Tag Group 3",
"subjectTagTypeId": 3,
"tagGroupHref": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/3",
"nodes": [
{
"id": 10,
"name": "Tag Value 1.1.0",
"shortCode": "1.1.0",
"parentNodeId": 4,
"subjectTagValueId": 10,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/10",
"contentCode": "1.1.1.1.1.0",
"contentCodeTagValueId": 25,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/25"
},
{
"id": 11,
"name": "Tag Value 1.1.1",
"shortCode": "1.1.1",
"parentNodeId": 4,
"subjectTagValueId": 11,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/11",
"contentCode": "1.1.1.1.1.1",
"contentCodeTagValueId": 26,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/26"
},
{
"id": 12,
"name": "Tag Value 1.1.2",
"shortCode": "1.1.2",
"parentNodeId": 4,
"subjectTagValueId": 12,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/12",
"contentCode": "1.1.1.1.1.2",
"contentCodeTagValueId": 27,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/27"
},
{
"id": 13,
"name": "Tag Value 1.2.0",
"shortCode": "1.2.0",
"parentNodeId": 5,
"subjectTagValueId": 13,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/13",
"contentCode": "1.1.2.1.2.0",
"contentCodeTagValueId": 28,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/28"
},
{
"id": 14,
"name": "Tag Value 1.3.0",
"shortCode": "1.3.0",
"parentNodeId": 6,
"subjectTagValueId": 14,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/14",
"contentCode": "1.1.3.1.3.0",
"contentCodeTagValueId": 29,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/29"
},
{
"id": 15,
"name": "Tag Value 1.2.1",
"shortCode": "1.2.1",
"parentNodeId": 5,
"subjectTagValueId": 15,
"tagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/15",
"contentCode": "1.1.2.1.2.1",
"contentCodeTagValueId": 30,
"contentCodeTagValueHref": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/30"
}
]
}
]
}
],
"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 tag hierarchies there are in total.
top integer
Details number of tag hierarchies returned in the response. This is null because the information retrieved is for a specific tag hierarchy.
skip integer
Details how many tag hierarchies were skipped to display those in the response. This is null because the information retrieved is for a specific tag hierarchy.
pageCount integer
Details how many pages of tag hierarchies there are. This is null because the information retrieved is for a specific tag hierarchy.
nextPageLink string
The endpoint to call the next page of tag hierarchies. This is null because the information retrieved is for a specific tag hierarchy.
prevPageLink string
The endpoint to call the previous page of tag hierarchies. This is null because the information retrieved is for a specific tag hierarchy.
response array
Contains the rest of the response.
subject object
Contains the subject that the tag hierarchy 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.
id integer
The tag hierarchy’s unique identifier.
name string
The tag hierarchy’s name.
shortCodesEnabled Boolean
Determines whether shortcodes are enabled for the tag hierarchy.
If enabled, when a tag value in a tag hierarchy is assigned to an item, the shortcodes of the tag and all its parent tags are combined into a new combined shortcode tag value that is then also assigned to the item.
contentCodeTagGroupName string
The name of the tag hierarchy’s combined shortcode tag group.
contentCodeTagTypeId integer
The combined shortcode tag group’s unique identifier. If null, shortcodes are not enabled for the tag hierarchy.
contentCodeTagGroupHref string
The endpoint to call the combined shortcode tag group’s information, such as /api/v2/TagGroup/{id} where {id} is the tag group’s unique identifier. If null, shortcodes are not enabled for the tag hierarchy.
isPublished Boolean
If true, the tag hierarchy’s status is Published and item authors can add add tags to items from the hierarchy.
tagHierarchyGroups array
Contains the tag hierarchy’s tag groups’ information. Each tag group represents a level of the tag hierarchy, in order of appearance.
tagHierarchyGroups/id integer
The tag group’s unique identifier.
tagHierarchyGroups/name string
The tag group’s name.
tagHierarchyGroups/subjectTagTypeId integer
The tag group’s unique identifier.
tagHierarchyGroups/tagGroupHref 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.
tagHierarchyGroups/nodes array
Contains the tag group’s tag values.
tagHierarchyGroups/nodes/id integer
The unique identifier for the tag value’s node position in the hierarchy.
tagHierarchyGroups/nodes/name string
The tag value’s name.
tagHierarchyGroups/nodes/shortcode string
The tag value’s shortcode.
tagHierarchyGroups/nodes/parentNodeId integer
The parent tag value’s unique identifier. If null, the tag value is in the first tag group and top-level of the tag hierarchy, and therefore has no parent tag value.
tagHierarchyGroups/nodes/subjectTagValueId integer
The tag value’s unique identifier.
tagHierarchyGroups/nodes/tagValueHref 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.
tagHierarchyGroups/nodes/contentCode string
The tag value’s combined shortcode tag value. When the tag value is assigned to an item, the tag value and all its parent tags are combined into a new combined shortcode tag value that is then also assigned to the item.
tagHierarchyGroups/nodes/contentCodeTagValueId integer
The tag value’s combined shortcode tag value’s unique identifier. If null, shortcodes are not enabled for the tag hierarchy.
tagHierarchyGroups/nodes/contentCodeTagValueHref string
The endpoint to call the combined shortcode’s tag value’s information, such as /api/v2/TagValue/{id} where {id} is the tag value’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 a tag hierarchy
Send a request to the endpoint to create a tag hierarchy.
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 a tag hierarchy.
{
"subject": {
"reference": "Subject1"
},
"name": "Tag Hierarchy 1"
}Response schema
The response schema contains a description of every property that can be returned for this endpoint.
subject object mandatory
Contains the subject that the tag hierarchy 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.
name string mandatory
The tag hierarchy’s name.
shortCodesEnabled Boolean optional
Determines whether shortcodes are enabled for the tag hierarchy. Defaults to false if omitted.
If enabled, when a tag value in a tag hierarchy is assigned to an item, the shortcodes of the tag and all its parent tags are combined into a new combined shortcode tag value that is then also assigned to the item.
contentCodeTagGroupName string optional
The name of the tag hierarchy’s combined shortcode tag group.
isPublished Boolean optional
If true, the tag hierarchy’s status is Published and item authors can add add tags to items from the hierarchy. If omitted, the tag hierarchy is created at Draft status.
tagHierarchyGroups array optional
Contains the tag hierarchy’s tag groups’ information. Each tag group represents a level of the tag hierarchy, in order of appearance.
tagHierarchyGroups/name string
The tag group’s name.
tagHierarchyGroups/nodes array
Contains the tag group’s tag values.
tagHierarchyGroups/nodes/uid integer
The unique identifier for the tag value’s node position in the hierarchy.
tagHierarchyGroups/nodes/name string
The tag value’s name.
tagHierarchyGroups/nodes/shortcode string
The tag value’s shortcode.
tagHierarchyGroups/nodes/parentNodeUid integer
The parent tag value’s unique identifier. If omitted, the tag value is in the first tag group and top-level of the tag hierarchy, and therefore has no parent tag value.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag hierarchy’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagHierarchy/1",
"errors": 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. |
|
NoSubjectsAssociated |
12 |
There are no subjects associated with what is defined in the request. |
|
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/TagHierarchy?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
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: