TagValue 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”.

Tags are made up of categorised containers called “tag groups” that contain individual tags called “tag values”. For example, a tag group called “difficulty” might have the following tag values: “Easy”, “Medium”, and “Hard”.

The TagValue API resource is used to list, retrieve, create, and update tag values. For information on tag groups, read TagGroup API. To learn how to add tag values to items, read ItemTagValue API.

This article explains what calls can be made to the Surpass API using the TagValue resource.

Import this API into your Postman Workspace

Listing tag values

get /api/v2/TagValue

Send a request to the endpoint to retrieve a list of tag values. 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.

EXAMPLE: The endpoint /api/v2/TagValue?$filter=TagGroup/id eq '1' would return all tag values that are in tag group 1.

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/TagValue?$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/TagValue?$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/TagValue?$filter={filter} {operator} {value}`	Filters results, searching for an exact match. For an exact match: `{filter}` is `TagGroup/id`, `deleted`, `{operator}` is `eq` (equal to), and `{value}` is the integer or Boolean the filter query looks for an exact match for in the request.
orderBy	query OPTIONAL	`/api/v2/TagValue?$orderBy={attribute}`	Determines order of results, where `{attribute}` is `id`.

TIP: Multiple query parameters can be passed in a request at once. filter parameters can be joined using and between attributes. top, skip, and other parameters are joined using &. For example, the endpoint /api/v2/TagValue?$top=10&$skip=25 would skip the first 25 results and return 10.

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": 3547,
    "top": 10,
    "skip": 0,
    "pageCount": 355,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/TagValue?$skip=10",
    "prevPageLink": null,
    "response": [
        {
            "tagValue": "Knowledge of European Geography",
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/1"
        },
        {
            "tagValue": "Knowledge of American History",
            "id": 2,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/2"
        },
        {
            "tagValue": "Knowledge of Chemical Structures",
            "id": 3,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/3"
        },
        {
            "tagValue": "Knowledge of English Literature",
            "id": 4,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/4"
        },
        {
            "tagValue": "Knowledge of Renaissance Art",
            "id": 5,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/5"
        },
        {
            "tagValue": "Knowledge of French Cuisine",
            "id": 6,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/6"
        },
        {
            "tagValue": "Knowledge of Social Sciences",
            "id": 7,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/7"
        },
        {
            "tagValue": "Knowledge of Abrahamic Religions",
            "id": 8,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/8"
        },
        {
            "tagValue": "Knowledge of Natural Philosophy",
            "id": 9,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/9"
        },
        {
            "tagValue": "Knowledge of Political Systems",
            "id": 10,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/10"
        }
    ],
    "errors": null,
    "serverTimeZone": "GMT Standard Time"
}

Retrieving tag value information

get /api/v2/TagValue/{id}

Send a request to the endpoint to retrieve information for a specific tag value using its ID. No request body is required.

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.

path

OPTIONAL

/api/v2/TagValue/{id}

Returns information for the specified tag value, where {id} is the tag value’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": [
        {
            "tagValue": "Knowledge of European Geography",
            "tagGroup": {
                "name": "Tag Group 1",
                "tagTypeKey": "Custom",
                "isHierarchicalTag": false,
                "id": 1,
                "href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
            },
            "id": 1,
            "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/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 values there are in total. This is null because the information retrieved is for a specific tag value.

top integer

Details number of tag values returned in the response. This is null because the information retrieved is for a specific tag value.

skip integer

Details how many tag values were skipped to display those in the response. This is null because the information retrieved is for a specific tag value.

pageCount integer

Details how many pages of tag values there are. This is null because the information retrieved is for a specific tag value.

nextPageLink string

The endpoint to call the next page of tag values. This is null because the information retrieved is for a specific tag value.

prevPageLink string

The endpoint to call the previous page of tag values. This is null because the information retrieved is for a specific tag value.

response array

Contains the rest of the response.

tagValue string

The name of the tag value.

tagGroup object

The tag group that contains the tag value.

tagGroup/name string

The name of the tag group.

tagGroup/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.

tagGroup/isHierarchicalTag Boolean

If true, the tag group is part of a tag hierarchy. For more information, read Setting up tag hierarchies.

tagGroup/tagHierarchy object

Contains the tag hierarchy’s information.

NOTE: This property is only returned if isHierarchicalTag is true.

tagGroup/tagHierarchy/id integer

The tag hierarchy’s unique identifier.

tagGroup/tagHierarchy/name string

The tag hierarchy’s name.

tagGroup/tagHierarchy/href string

The endpoint to call the tag hierarchy’s information, such as /api/v2/TagHierarchy/{id} where {id} is the tag hierarchy’s unique identifier.

tagGroup/id integer

The tag group’s unique identifier.

tagGroup/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.

deleted Boolean

Determines whether the tag value is deleted or not.

NOTE: The deleted object is only returned if the tag value has been deleted and is therefore true.

id integer

The tag value’s unique identifier.

href string

The endpoint to call the tag value’s information, such as /api/v2/TagValue/{id} where {id} is the tag value’s unique identifier.

shortcode string

The tag value’s shortcode.

NOTE: This property is only returned if isHierarchicalTag is true and tag hierarchy shortcodes are enabled.

isContentCodeTagValue Boolean

Determines whether the tag value is an assigned combined shortcode tag value.

NOTE: This property is only returned if isHierarchicalTag is true, tag hierarchy shortcodes are enabled, and the tag value is an assigned combined shortcode tag value.

contentCodeTagValueId integer

The combined shortcode tag value’s unique identifier if the tag value is part of an assigned combined shortcode tag value.

NOTE: This property is only returned if isHierarchicalTag is true, tag hierarchy shortcodes are enabled, and the tag value is part of an assigned combined shortcode tag value.

contentCode string

The tag value’s combined shortcode tag value. When the tag value is assigned to an item, the tag value and all its parent tags are combined into a new combined shortcode tag value that is then also assigned to the item.

NOTE: This property is only returned if isHierarchicalTag is true and tag hierarchy shortcodes are enabled.

relatedTagValueId integer

The unique identifier of another tag value in the chain of tag values if the tag value is part of an assigned combined shortcode tag value.

NOTE: This property is only returned if isHierarchicalTag is true, tag hierarchy shortcodes are enabled, and the tag value is part of an assigned combined shortcode tag value.

parentTagValueId integer

The unique identifier of the tag value’s parent tag value.

NOTE: This property is only returned if isHierarchicalTag is true.

errors string

Information about any errors that occurred during the request.

serverTimeZone enumeration

The timezone of the server sending the response.

Creating a tag value

post /api/v2/TagValue

Send a request to the endpoint to create a tag value.

IMPORTANT: Numeric tag values cannot be created using this API. To create a numeric tag value, assign one to an item directly using the ItemTagValue API.

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 value.

{
    "tagGroup": {
        "Id": 1
    },
    "tagValue": "Knowledge of European Geography"
}

EXAMPLE: In this sample request, a tag value called Knowledge of European Geography is created within the tag group 1.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the new tag value’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/1",
    "errors": null
}

Updating a tag value

put /api/v2/TagValue/{id}

Send a request to the endpoint to update a specific tag value.

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/TagValue/{id}`	Update specified tag value, where `{id}` is the tag value’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 value. Refer to the request body schema for all properties that can be updated.

{
    "tagValue": "Knowledge of American History"
}

EXAMPLE: In this sample request, the tag value has been renamed to Knowledge of American History.

Sample response

If successful, the HTTP status code will be 200 and the response body will contain the updated tag value’s details.

{
    "id": 1,
    "href": "https://{your Surpass instance}.surpass.com/api/v2/TagValue/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.
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/TagValue?$skip={skip}` query parameter, where `{skip}` is a number that should not exceed the total number of responses.
FailedToCreateTagValue	60	There is an issue with creating the tag value.
TagValueDoesNotExist	61	The tag value specified in the request does not exist.

TagValue API

In This Article

Listing tag values

Parameters

Sample response

Response schema

Retrieving tag value information

Parameters

Sample response

Response schema

Creating a tag value

Parameters

Sample request

Request body schema

Sample response

Updating a tag value

Parameters

Sample request

Request body schema

Sample response

Error Codes

Further reading

About the site