TagGroup Resource

Using the TagGroup Resource on the Surpass API, it is possible to search, filter and create tag groups in Surpass using GET and POST requests. Existing tag groups can also be updated using a PUT request.

TagGroup Resource

Below we have listed the operations, HTTP verbs and an example URL for the TagGroup resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/TagGroup
Filter GET https://...surpass.com/api/v2/TagGroup?$filter=contains(name, 'Learning Outcomes')
Read (Individual by ID) GET https://...surpass.com/api/v2/TagGroup/
Create POST https://...surpass.com/api/v2/TagGroup/
Update PUT https://...surpass.com/api/v2/TagGroup/{id}
Fetch Tag Groups GET https://...surpass.com/api/v2/TagGroup/ItemListTagGroups/{list id}

Attributes for the TagGroup Resource

In the table below we have provided all of the attributes included in the TagGroup Resource. This includes: the attribute name, data type, if the attribute is orderable when requesting the GET method and if the attribute is available to filter when requesting the GET method.
Attribute Name Type Description Order (GET) Filter (GET) Unique Identifier Mandatory for Create (POST) Default
subject resource ID or Ref can be supplied X X
id string The unique identifier for the tag group. X X X X
href string The link to call the TagGroup Resource.
name string The name of the tag group in Surpass. Name will only be presented in GET response if tagTypeKey is ‘Custom’.
authorCreation boolean Allows the item author to create their own tags under this tag group when 'True'. false
allowMultipleTags boolean This controls the number of tags per item. 'True' allows multiple tags per item. 'False' will restrict to one tag from this tag group per item. true
Prevents item authors without the 'Read-only Tag Groups' permission from adding or removing tag values from the tag group when 'True'.
Allows the tag group to be used in tag collections when 'True'.
The id and href of any tag categories the tag group is associated with.

tagTypeKey string The type of tag group. This will be one of the following default tag groups: ‘Learning Outcomes’, ‘Keywords’, ‘Units’; or a ‘Custom’ tag group.
tagTypeValue string The tag group type. ‘Text’ or ‘Numeric’.
categoryName string Name of Category to which Group belongs
groupName string Name of Tag Group
categoryId long Unique CategoryID
groupId long Unique GroupID
tagTypeKey short Key to differentiate tag type (Possible values: 1 = learning outcome, 2 = Units, 3 = Keyword, 4 = Custom)
type string The type of numeric tag. ‘Range’, ‘LessThan’, ‘GreaterThan’ or ‘Custom’.
lowerBoundary The lower boundary or 'from' value in Surpass. Used when numeric tag type is 'Range'.
upperBoundary integer The upper boundary or 'to' value in Surpass. Used when numeric tag type is 'Range'.
boundary The boundary for use with ‘LessThan’ or ‘GreaterThan’ numeric tag types.
allowDecimalPlaces boolean Allows decimal places with the numeric tags when 'true'. Cannot be updated with PUT request.
Additional Notes
  • Name is the Tag Group’s display name in Surpass.
  • AllowMultipleTags enables the item author to take multiple tags from this group and add them to an item. If this is set to false, only one tag from a Tag Group can be used.
  • AuthorCreation determines whether authors can create their own tags during the authoring process. If false, authors can only choose from a list of pre-defined tags.

GET Request and Return

The GET TagGroup Resource can be called directly by browsing to the URL. Any required parameters such as $filter, $orderBy, $skip and $top would need to form part of the URL that is sent. Below we have provided examples of JSON and XML responses that would be returned from the Surpass API when requesting the GET method for the TagGroup Resource. It is important to remember that the return information will be included within the response object that forms part of the standard GET response; this is detailed in the page "Understanding the Surpass API".

Example GET request & response (JSON)
Example GET request & response (XML)

POST Request and Return

The POST TagGroup method requires the attributes listed above to be submitted as part of the body of the HTTPS request. This can be submitted in either JSON or XML format. The content-type used will need to be submitted as part of the header of the request. An example of the address, header and body of the request (for both formats) can be found below.

Example POST request & response (JSON)
Example POST request & response (XML)

PUT Request and Return

PUT Requests should reference the ID within the resource. The resource being updated should be included in the body of the request and can be sent in either JSON or XML format. Only the field you want to be updated needs to be included within the requesta and all others can be omitted; these fields will retain their current values. The content-length, content-type and Authorization will also be required in the header of the request.

All attributes included in the body of the PUT request are optional. If an attribute is omitted it will retain its current value set in the DB. You cannot update a multiple tag group to a single tag group because items might have had multiple tags assigned.

Example PUT request (JSON & XML)

Required Permissions

To successfully call the TagValue methods, the user specified in the header of the request must have the ‘Manage Subjects’ permission in Surpass.  

Feedback and Knowledge Base