TagCategory API
A tag category can be used to categorise tag groups and tag values. You can create tag categories in the Subjects screen of Setup.
The TagCategory API resource is used to list, retrieve, create, update, and delete tag categories.
This article explains what calls can be made to the Surpass API using the TagCategory resource.
Import this API into your Postman Workspace
In This Article
Listing tag categories
Send a request to the endpoint to retrieve a list of tag categories. 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 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/TagCategory?$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/TagCategory?$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/TagCategory?$filter={filter} {operator} {value} |
Filters results, searching for an exact match. For an exact match: {filter} is subject/id, subject/reference, {operator} is eq (equal to), and {value} is the string or integer the filter query looks for an exact match for in the request. |
|
orderBy |
query OPTIONAL |
/api/v2/TagCategory?$orderBy={attribute} |
Determines order of results, where {attribute} is id. |
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": 23,
"top": 10,
"skip": 0,
"pageCount": 3,
"nextPageLink": "https://{your Surpass instance}.surpass.com:443/api/v2/TagCategory?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/1"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/2"
},
{
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/3"
},
{
"id": 4,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/4"
},
{
"id": 5,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/5"
},
{
"id": 6,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/6"
},
{
"id": 7,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/7"
},
{
"id": 8,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/8"
},
{
"id": 9,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/9"
},
{
"id": 10,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/10"
}
],
"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 categories there are in total.
top integer
Details number of tag categories returned in the response.
skip integer
Details how many tag categories were skipped to display those in the response.
pageCount integer
Details how many pages of tag categories there are.
nextPageLink string
The endpoint to call the next page of tag categories. If null, the response is the last page of tag categories.
prevPageLink string
The endpoint to call the previous page of tag categories. If null, the response is the first page of tag categories.
response array
Contains the rest of the response.
id integer
The tag category’s unique identifier.
href string
The endpoint to call the tag category’s information, such as /api/v2/TagCategory/{id} where {id} is the tag category’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Retrieving tag category information
Send a request to the endpoint to retrieve information for a specific tag category 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 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. |
|
id |
path OPTIONAL |
/api/v2/TagCategory/{id} |
Returns information for the specified tag category, where {id} is the tag category’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": [
{
"name": "Humanities",
"tagGroups": [
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
},
{
"id": 2,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/2"
},
{
"id": 3,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/3"
}
],
"subject": {
"id": 1,
"reference": "Subject 1"
},
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/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 categories there are in total. This is null because the information retrieved is for a specific tag category.
top integer
Details number of tag categories returned in the response. This is null because the information retrieved is for a specific tag category.
skip integer
Details how many tag categories were skipped to display those in the response. This is null because the information retrieved is for a specific tag category.
pageCount integer
Details how many pages of tag categories there are. This is null because the information retrieved is for a specific tag category.
nextPageLink string
The endpoint to call the next page of tag categories. This is null because the information retrieved is for a specific tag category.
prevPageLink string
The endpoint to call the previous page of tag categories. This is null because the information retrieved is for a specific tag category.
response array
Contains the rest of the response.
name string
The name of the tag category.
tagGroups array
Contains the information of the tag groups in the tag category.
tagGroups/id integer
The tag group’s unique identifier.
tagGroups/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.
subject object
Contains the subject that the tag category is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
id integer
The tag category’s unique identifier.
href string
The endpoint to call the tag category’s information, such as /api/v2/TagCategory/{id} where {id} is the tag category’s unique identifier.
errors string
Information about any errors that occurred during the request.
serverTimeZone enumeration
The timezone of the server sending the response.
Creating a tag category
Send a request to the endpoint to create a tag category.
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 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 category.
{
"name": "Humanities",
"subject": {
"reference": "Subject 1"
}
}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 category.
subject object mandatory
Contains the subject that the tag category is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
tagGroups array optional
Contains the information of any tag groups in the tag category.
tagGroups/id integer
The tag group’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag category’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/1",
"errors": null,
"serverTimeZone": null
}Updating a tag category
Send a request to the endpoint to update a specific tag category.
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 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/TagCategory/{id} |
Update specified tag category, where {id} is the tag category’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 category. Refer to the request body schema for all properties that can be updated.
{
"name": "Sciences"
}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 category.
tagGroups array
Contains the information of any tag groups in the tag category.
tagGroups/id integer
The tag group’s unique identifier.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the updated tag category’s details.
{
"id": 1,
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCategory/1",
"errors": null,
"serverTimeZone": null
}Deleting a tag category
Send a request to the endpoint to delete a specific tag category. 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 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. |
|
id |
path MANDATORY |
/api/v2/TagCategory/{id} |
Deletes specified tag category, where {id} is the tag category’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the tag category 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.
|
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. |
|
NoSubjectsAssociated |
12 |
There are no subjects associated with what is defined in the request. |
|
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/TagCategory?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
|
FailedToCreateTagCategory |
174 |
There is an issue with creating the tag category |
|
TagCategoryDoesNotExist |
176 | There is an issue with deleting the tag category. |
Further reading
Read the following articles to learn more about similar APIs, how to get started with the Surpass API v2, and how to get the best out of this reference documentation: