TagCategory Resource

In Surpass tag categories are used to group different item tag groups. It might be that some of the item tag groups you use on items are reporting based and others are more operation or content related. Tag Categories can be used in this example to make sure that they appear to the author in a logical order, so reporting tags are displayed together and content related tags are separate. Using the TagCategory Resource on the Surpass API, it is possible to search, filter, create and delete tag categories in Surpass using GET, POST, PUT and DELETE requests.

Below we have provided further context and examples around the entities relationship:
  • Tag categories contain one to many tag groups, 'content' or 'Reporting Data' could be an example tag category that houses tag groups with names such as 'learning outcome', 'image used', 'translated item id'. 
  • Tag groups contain one to many tag values, an example being 'P Value', 'IRT Value',  'translated item id' etc...
  • Tag values are the actual value assigned to the item, for example '0.7', '123P123', 'Learning Outcome Example'
TagCategory Resource

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

Attributes for the TagCategory Resource

In the table below we have provided all of the attributes included in the TagCategory Resource. This includes: the attribute name, data type, description, 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 Filter (GET) Unique Identifier Mandatory for Create (POST) Default
id int The unique identifier for the tag category. X X
href string The link to call the individual TagCategory Resource. n/a
name string The name of the tag category in Surpass.  X
tagGroups resource The tag groups that have been included and presented within the tag category. ID is required. null
subject resource The subject the tag category belongs to.
ID or reference can be specified.
(id or reference)
Additional Notes
  • Name is unique within a subject
GET Request and Return

The GET TagCategory 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 TagCategory 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 / PUT Request and Return

The POST TagCategory 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 request (for both formats) can be found below.

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

Feedback and Knowledge Base