TagGroup 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 are categorised containers for tag values. You can create tag groups in the Subjects screen of Setup. Tag groups are subject-specific.
The TagGroup API resource is used to list, retrieve, create, and update tag groups. For information on tag values, read TagValue API.
This article explains what calls can be made to the Surpass API using the TagGroup resource.
Import this API into your Postman Workspace
In This Article
Listing tag groups
Send a request to the endpoint to retrieve a list of tag groups. 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/TagGroup?$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/TagGroup?$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/TagGroup?$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. |
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": 1118,
"top": 10,
"skip": 0,
"pageCount": 112,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/TagGroup?$skip=10",
"prevPageLink": null,
"response": [
{
"tagTypeKey": "LearningOutcome",
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
{
"tagTypeKey": "Unit",
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/2"
},
{
"tagTypeKey": "Keyword",
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/3"
},
{
"tagTypeKey": "LearningOutcome",
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/4"
},
{
"tagTypeKey": "Unit",
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/5"
},
{
"tagTypeKey": "Keyword",
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/6"
},
{
"tagTypeKey": "LearningOutcome",
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/7"
},
{
"tagTypeKey": "Unit",
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/8"
},
{
"tagTypeKey": "Keyword",
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/9"
},
{
"tagTypeKey": "LearningOutcome",
"id": 10,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/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 tag groups there are in total.
top integer
Details number of tag groups returned in the response.
skip integer
Details how many tag groups were skipped to display those in the response.
pageCount integer
Details how many pages of tag groups there are.
nextPageLink string
The endpoint to call the next page of tag groups. If null, the response is the last page of tag groups .
prevPageLink string
The endpoint to call the previous page of tag groups . If null, the response is the first page of tag groups.
response array
Contains the rest of the response.
name string
The name of the tag group.
tagTypeKey enumeration
The type of tag group. The default tag groups in Surpass are LearningOutcome, Unit, and Keyword. Users can also create Custom tag groups.
id integer
The tag group’s unique identifier.
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.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Listing tag groups in item lists
Send a request to the endpoint to retrieve a list of tag groups from subjects whose items are on the specified item list. 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. |
|
id |
path MANDATORY |
/api/v2/TagGroup/ItemListTagGroups/{id} |
Returns information for the specified item list, where {id} is the item list’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": 3,
"top": null,
"skip": null,
"pageCount": null,
"nextPageLink": null,
"prevPageLink": null,
"response": [
{
"categoryName": "Uncategorised",
"groupName": "Learning Outcomes",
"categoryId": -1,
"groupId": 1,
"tagTypeKey": 1
},
{
"categoryName": "Uncategorised",
"groupName": "Units",
"categoryId": -1,
"groupId": 2,
"tagTypeKey": 2
},
{
"categoryName": "Uncategorised",
"groupName": "Keywords",
"categoryId": -1,
"groupId": 3,
"tagTypeKey": 3
}
],
"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 groups there are in total.
top integer
Details number of tag groups returned in the response. This property is always returned as null.
skip integer
Details how many tag groups were skipped to display those in the response. This property is always returned as null.
pageCount integer
Details how many pages of tag groups there are. This property is always returned as null.
nextPageLink string
The endpoint to call the next page of tag groups. This property is always returned as null.
prevPageLink string
The endpoint to call the previous page of tag groups. This property is always returned as null.
response array
Contains the rest of the response.
categoryName string
The name of the tag category the tag group belongs to. If the tag group does not belong to a category, categoryName will return the name ‘Uncategorised’.
groupName string
The name of the tag group. The default tag groups in Surpass are ‘Learning Outcomes’, ‘Units’, and ‘Keywords’. Users can also create custom tag groups.
categoryId integer
The unique identifier for the tag category the tag group is a part of. If -1, the tag group is not part of any tag categories.
groupId integer
The tag group’s unique identifier.
tagTypeKey enumeration
The type of tag group. The default tag groups in Surpass are ‘Learning Outcomes’ (1), ‘Units’ (2), and ‘Keywords’ (3). Users can also create custom (4) tag groups.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving tag group information
Send a request to the endpoint to retrieve information for a specific tag group 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/TagGroup/{id} |
Returns information for the specified tag group, where {id} is the tag group’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": "Tag Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject/1",
"name": null
},
"authorCreation": false,
"allowMultipleTags": true,
"isReadOnly": false,
"isFeatured": false,
"isCollectable": false,
"isPublishable": true,
"isHierarchicalTag": false,
"tagCategories": [],
"tagTypeKey": "LearningOutcome",
"tagTypeValue": "Text",
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/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 tag groups there are in total.
top integer
Details number of tag groups returned in the response. This is null because the information retrieved is for a specific tag group.
skip integer
Details how many tag groups were skipped to display those in the response. This is null because the information retrieved is for a specific tag group.
pageCount integer
Details how many pages of tag groups there are. This is null because the information retrieved is for a specific tag group.
nextPageLink string
The endpoint to call the next page of tag groups. This is null because the information retrieved is for a specific tag group.
prevPageLink string
The endpoint to call the previous page of tag groups. This is null because the information retrieved is for a specific tag group.
response array
Contains the rest of the response.
subject object
Contains the subject that the tag group 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.
authorCreation Boolean
If true, item authors can create their own tag values from within subjects. If false, item authors can only select from predetermined tag values created by subject owners.
allowMultipleTags Boolean
If true, multiple tags can be added to the tag group. If false, only one tag value can be added to this tag group per item.
isReadOnly Boolean
If true, prevents item authors without the Read-only Tag Groups permission from adding or removing tag values from the tag group. For more information, read About roles and permissions.
isFeatured Boolean
If true, the tag group is a featured tag group. For more information, read ‘Featuring tag groups’ in Setting up tag groups.
isCollectable Boolean
If true, the tag group can be used in tag collections. For more information, read Using tag collections in items.
isPublishable Boolean
If true, tags in the tag group are published from Item Authoring to Test Creation.
isHierarchicalTag Boolean
If true, the tag group is part of a tag hierarchy. For more information, read Setting up tag hierarchies.
tagCategories array
Contains any tag categories the tag group is part of. For more information, read Setting up tag categories.
tagCategories/id integer
The tag category’s unique identifier. For more information, read Setting up tag categories.
tagCategories/href string
The endpoint to call the tag category’s information, such as /api/v2/TagCategory/{id} where {id} is the tag category’s unique identifier.
tagTypeKey enumeration
The type of tag group. The default tag groups in Surpass are LearningOutcome, Unit, and Keyword. Users can also create Custom tag groups.
tagTypeValue enumeration
Determines whether the tag values in the group are Text or Numeric.
numericTagProperties object
Contains the settings for numeric tag groups. For more information, read ‘Setting up numeric tag values’ in Setting up tag groups.
numericTagProperties/type enumeration
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan.
numericTagProperties/boundary integer
The value specified to be the boundary (less than, greater than, or equal to) for the tag values if the numeric tag group type is LessThan or GreaterThan. If null, the numeric tag group type is Custom or a Range.
numericTagProperties/lowerBoundary integer
The value specified to be the lower boundary if the numeric tag group type is a Range. If null the numeric tag group type is Custom, LessThan, or GreaterThan.
numericTagProperties/upperBoundary integer
The value specified to be the upper boundary if the numeric tag group type is a Range. If null if the numeric tag group type is Custom, LessThan, or GreaterThan.
numericTagProperties/allowDecimalPlaces Boolean
Determines whether tag values in the tag group can contain decimal places.
id integer
The tag group’s unique identifier.
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.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a tag group
Send a request to the endpoint to create a tag group.
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 group.
{
"subject": {
"reference": "Subject1"
},
"name": "Tag Group 1"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
subject object mandatory
Contains the subject that the tag group is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
allowMultipleTags Boolean optional
If true, multiple tags can be added to the tag group. If false, only one tag value can be added to this tag group per item. Defaults to true if omitted.
isFeatured Boolean optional
If true, the tag group is a featured tag group. For more information, read ‘Featuring tag groups’ in Setting up tag groups. Defaults to false if omitted.
isCollectable Boolean optional
If true, the tag group can be used in tag collections. For more information, read Using tag collections in items. Defaults to false if omitted.
isPublishable Boolean optional
If true, tags in the tag group are published from Item Authoring to Test Creation. Defaults to true if omitted.
authorCreation Boolean optional
If true, item authors can create their own tag values from within subjects. If false, item authors can only select from predetermined tag values created by subject owners. Defaults to false if omitted.
isReadOnly Boolean optional
If true, prevents item authors without the Read-only Tag Groups permission from adding or removing tag values from the tag group. For more information, read About roles and permissions. Defaults to false if omitted.
tagTypeValue enumeration optional
Determines whether the tag values in the group are Text or Numeric.
numericTagProperties object optional
Contains the settings for numeric tag groups. For more information, read ‘Setting up numeric tag values’ in Setting up tag groups.
numericTagProperties/type enumeration
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan.
numericTagProperties/boundary integer
The value specified to be the boundary (less than, greater than, or equal to) for the tag values if the numeric tag group type is LessThan or GreaterThan.
numericTagProperties/lowerBoundary integer
The value specified to be the lower boundary if the numeric tag group type is a Range.
numericTagProperties/upperBoundary integer
The value specified to be the upper boundary if the numeric tag group type is a Range.
numericTagProperties/allowDecimalPlaces Boolean
Determines whether tag values in the tag group can contain decimal places.
tagCategories array optional
Contains any tag categories the tag group is part of.
tagCategories/id integer
The tag category’s unique identifier.
name string mandatory
The name of the tag group.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag group’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1",
"errors": null
}Updating a tag group
Send a request to the endpoint to update a specific tag group.
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/TagGroup/{id} |
Update specified tag group, where {id} is the tag group’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 a tag group. Refer to the request body schema for all properties that can be updated.
{
"isCollectable": true
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
allowMultipleTags Boolean
If true, multiple tags can be added to the tag group. If false, only one tag value can be added to this tag group per item.
isFeatured Boolean
If true, the tag group is a featured tag group. For more information, read ‘Featuring tag groups’ in Setting up tag groups.
isCollectable Boolean
If true, the tag group can be used in tag collections. For more information, read Using tag collections in items.
isPublishable Boolean
If true, tags in the tag group are published from Item Authoring to Test Creation.
authorCreation Boolean
If true, item authors can create their own tag values from within subjects. If false, item authors can only select from predetermined tag values created by subject owners.
isReadOnly Boolean
If true, prevents item authors without the Read-only Tag Groups permission from adding or removing tag values from the tag group. For more information, read About roles and permissions.
numericTagProperties object
Contains the settings for numeric tag groups. For more information, read ‘Setting up numeric tag values’ in Setting up tag groups.
numericTagProperties/type enumeration
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan.
numericTagProperties/boundary integer
The value specified to be the boundary (less than, greater than, or equal to) for the tag values if the numeric tag group type is LessThan or GreaterThan.
numericTagProperties/lowerBoundary integer
The value specified to be the lower boundary if the numeric tag group type is a Range.
numericTagProperties/upperBoundary integer
The value specified to be the upper boundary if the numeric tag group type is a Range.
numericTagProperties/allowDecimalPlaces Boolean
Determines whether tag values in the tag group can contain decimal places.
tagCategories array
Contains any tag categories the tag group is part of.
tagCategories/id integer
The tag category’s unique identifier.
name string
The name of the tag group.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated tag group’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/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/TagGroup?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
BadRequest |
63 |
Validation on a tag group setting prevented a successful PUT request. For example:
|
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: