TagValue Resource

In Surpass, you have the ability to create tags which can be assigned to question items and then used to search for items when compiling a test, and view results by once a test has been marked. The default tag groups are Learning Outcome, Unit, and Keywords, but additional tag groups may have been created at subject level. Using the TagValue Resource on the Surpass API, it is possible to search and filter tag values, return all attributes for an individual tag value, create tags via a POST request and also update existing tag values.

TagValue Resource

Below we have listed the operations, HTTP verbs and an example URL for the TagValue resource within the Surpass API.
Operation HTTP Verb Example URL
List GET https://...surpass.com/api/v2/TagValue
Filter GET https://...surpass.com/api/v2/TagValue?$filter=contains(tagValue, ‘Reptiles’)
Read (Individual by ID) GET https://...surpass.com/api/v2/TagValue/17
Create POST https://...surpass.com/api/v2/TagValue
Update PUT https://...surpass.com/api/v2/TagValue/17

Attributes for the TagValue Resource

Within the table below we have provided all of the attributes included in the TagValue 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) Available Operators (GET) Unique Identifier Mandatory for Create (POST) Default Max Length
Id Int The unique identifier for the tag value. Unable to POST/PUT. X X Numeric OData Operators X
tagValue string The name or value of the tag. X X String OData operators X X 500
href string The link to call the TagValue Resource. Unable to POST/PUT. N/A
deleted boolean X X eq false
TagGroup Resource ID or Name can be supplied X X * X X
*- numeric OData operators for Id; string OData operators for name.

Additional Notes
  • ID is the unique identifier for this resource in the Database.

GET Request and Return

The GET TagValue 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 TagValue 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 and response (JSON)
Example GET request and response (XML)

POST Request and Return

The POST TagValue 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 and response (JSON)
Example POST request and 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 request 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.

Example PUT request and response (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