TagGroup 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”.
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 OAPI resource is used to list, retrieve, create, update, and delete tag groups. For information on tag values, read TagValue OAPI.
This article explains what calls can be made to the Surpass OAPI 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 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/TagGroup?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: multipleValuesAllowed, authorValuesAllowed, deleted, tagValues, isActive, restrictions, valuesType, isCollectable, isReadOnly, isFeatured. |
|
filter |
query OPTIONAL |
/oapi/TagGroup?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, subject.id, subject.reference, subject.name, name, multipleValuesAllowed, authorValuesAllowed, deleted, isActive, restrictions.type, valuesType, isCollectable, isReadOnly, isPublishable, isFeatured; {operator} is eq (equal to); and {value} is the string, Boolean, or integer the filter query looks for an exact match for in the request. For a greater than query: {filter} is id, subject.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, subject.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 name, subject.reference, subject.name; {operator} is contains; and {value} is the string the filter query looks for an exact match for in the request. |
|
filterGrouping |
query OPTIONAL |
/oapi/TagGroup?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/TagGroup?filter=id le 10&filter=deleted eq true&filterGrouping=0 OR 1 would return both tag groups with a unique identifier less than 10 (0) and deleted tag groups (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/TagGroup?orderBy=fieldName={fieldName} |
Determines order of results, where {fieldName} is one of id, name, subject.id. |
|
take |
query OPTIONAL |
/oapi/TagGroup?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/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. |
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": 879,
"top": 10,
"skip": 0,
"totalPages": 88,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/TagGroup?Skip=10&Take=10",
"previousPageLink": null,
"results": [
{
"id": 1,
"name": "Tag Group 1",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 2,
"name": "Tag Group 2",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 3,
"name": "Tag Group 3",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 4,
"name": "Tag Group 4",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 5,
"name": "Tag Group 5",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 6,
"name": "Tag Group 6",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 7,
"name": "Tag Group 7",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 8,
"name": "Tag Group 8",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 9,
"name": "Tag Group 9",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
},
{
"id": 10,
"name": "Tag Group 10",
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
}
}
],
"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.
totalPages 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.
previousPageLink string
The endpoint to call the previous page of tag groups . If null, the response is the first page of tag groups.
results array
Contains the rest of the response.
id integer
The tag group’s unique identifier.
name string
The name of the tag group.
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/name string
The subject’s name.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.
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 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 |
path OPTIONAL |
/oapi/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 JSON format as requested.
{
"response": {
"id": 1,
"subject": {
"id": 1,
"reference": "Subject1",
"name": "Geography Subject",
"href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
},
"name": "Tag Group 1",
"multipleValuesAllowed": false,
"authorValuesAllowed": false,
"deleted": false,
"tagValues": [
{
"id": 1,
"name": "Knowledge of European Geography"
},
{
"id": 2,
"name": "Knowledge of American History"
},
{
"id": 3,
"name": "Knowledge of Chemical Structures"
},
{
"id": 4,
"name": "Knowledge of English Literature"
},
{
"id": 5,
"name": "Knowledge of Renaissance Art"
}
],
"isActive": true,
"restrictions": null,
"type": "Custom",
"valuesType": "Text",
"isCollectable": true,
"isReadOnly": true,
"isPublishable": true,
"isFeatured": false
},
"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 group’s unique identifier.
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/name string
The subject’s name.
subject/href string
The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.
name string
The name of the tag group.
multipleValuesAllowed 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.
authorValuesAllowed 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.
deleted Boolean
Determines whether the tag value is deleted or not.
tagValues array
Contains the information of all the tag values in the tag group.
tagValues/id integer
The tag value’s unique identifier.
tagValues/name string
The name of the tag value.
isActive Boolean
Determines whether any of the tag group’s tag values have been assigned to an item. If false, the tag group is inactive because no tag values are assigned to items.
restrictions/type
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan. If null, the tag group is not a numeric tag group.
restrictions/lowerBound integer
The value specified to be the boundary for the tag values if the numeric tag group type is LessThan or GreaterThan, or the lower boundary if the numeric tag group type is a Range.
restrictions/upperBound integer
The value specified to be the upper boundary if the numeric tag group type is a Range.
restrictions/allowDecimal Boolean
Determines whether tag values in the tag group can contain decimal places.
type enumeration
The type of tag group. The default tag groups in Surpass are LearningOutcome, Unit, and Keyword. Users can also create Custom tag groups.
valuesType enumeration
Determines whether the tag values in the group are Text or Numeric.
isCollectable Boolean
If true, the tag group can be used in tag collections. For more information, read Using tag collections in items.
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.
isPublishable Boolean
If true, tags in the tag group are published from Item Authoring to Test Creation.
isFeatured Boolean
If true, the tag group is a designated featured tag group.
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 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 group.
{
"name": "Tag Group 1",
"subject": {
"reference": "Subject1"
}
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
name string mandatory
The name of the tag group.
multipleValuesAllowed 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.
authorValuesAllowed 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.
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.
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.
isPublishable Boolean optional
If true, tags in the tag group are published from Item Authoring to Test Creation. Defaults to true if omitted.
isFeatured Boolean optional
If true, the tag group is a designated featured tag group. Defaults to false if omitted
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.
valuesType enumeration optional
Determines whether the tag values in the group are Text or Numeric.
restrictions object optional
Contains the settings for numeric tag groups. For more information, read ‘Setting up numeric tag values’ in Setting up tag groups.
restrictions/type enumeration
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan.
restrictions/lowerBound integer
The value specified to be the boundary for the tag values if the numeric tag group type is LessThan or GreaterThan, or the lower boundary if the numeric tag group type is a Range.
restrictions/upperBound integer
The value specified to be the upper boundary if the numeric tag group type is a Range.
restrictions/allowDecimal Boolean
Determines whether tag values in the tag group can contain decimal places.
tagValues array
Contains any tag values to be created in the new 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.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}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 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). |
|
id |
path MANDATORY |
/oapi/TagGroup/{id} |
Updates 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.
name string
The name of the tag group.
multipleValuesAllowed 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.
authorValuesAllowed 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.
restrictions object
Contains the settings for numeric tag groups. For more information, read ‘Setting up numeric tag values’ in Setting up tag groups.
restrictions/type enumeration
Determines whether the tag values in the numeric tag group are Custom, a Range, LessThan, or GreaterThan.
restrictions/lowerBound integer
The value specified to be the boundary for the tag values if the numeric tag group type is LessThan or GreaterThan, or the lower boundary if the numeric tag group type is a Range.
restrictions/upperBound integer
The value specified to be the upper boundary if the numeric tag group type is a Range.
isCollectable Boolean
If true, the tag group can be used in tag collections. For more information, read Using tag collections in items.
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.
isPublishable Boolean
If true, tags in the tag group are published from Item Authoring to Test Creation.
isFeatured Boolean
If true, the tag group is a designated featured 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.
{
"response": 1,
"serverTimeZone": "GMT Standard Time"
}Deleting a tag group
Send a request to the endpoint to delete a specific tag group. 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 |
path MANDATORY |
/oapi/TagGroup/{id} |
Deletes 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 confirm the item 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.
|
Code |
Description |
|---|---|
|
400 |
Indicates one of the following issues:
|
|
401 |
The request has been sent by an unauthorised user. |
|
403 |
Tag group cannot be accessed. |
|
404 |
Tag group does not exist. |
|
405 |
Validation on a tag group setting prevented a successful PUT request. For example:
|
Further reading
Read the following articles to learn how to get started with the Surpass OAPI or more about similar APIs: