TagCollectionGroup API
A tag collection group contains tag collections. A tag collection lets users group tag values from across different tag values. You can set up a tag collection group in the Subjects screen of Setup.
The TagCollectionGroup API resource is used to list, retrieve, create, and delete tag collection groups.
This article explains what calls can be made to the Surpass API using the TagCollectionGroup resource.
Import this API into your Postman Workspace
In This Article
Listing tag collection groups
Send a request to the endpoint to retrieve a list of tag collection groups. 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/TagCollectionGroup?$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/TagCollectionGroup?$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. |
|
orderBy |
query OPTIONAL |
/api/v2/TagCollectionGroup?$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/TagCollectionGroup?$skip=10",
"prevPageLink": null,
"response": [
{
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/1"
},
{
"id": 2,
"reference": "Tag Collection Group 2",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/2"
},
{
"id": 3,
"reference": "Tag Collection Group 3",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/3"
},
{
"id": 4,
"reference": "Tag Collection Group 4",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/4"
},
{
"id": 5,
"reference": "Tag Collection Group 5",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/5"
},
{
"id": 6,
"reference": "Tag Collection Group 6",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/6"
},
{
"id": 7,
"reference": "Tag Collection Group 7",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/7"
},
{
"id": 8,
"reference": "Tag Collection Group 8",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/8"
},
{
"id": 9,
"reference": "Tag Collection Group 9",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/9"
},
{
"id": 10,
"reference": "Tag Collection Group 10",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/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 collection groups there are in total.
top integer
Details number of tag collection groups returned in the response.
skip integer
Details how many tag collection groups were skipped to display those in the response.
pageCount integer
Details how many pages of tag collection groups there are.
nextPageLink string
The endpoint to call the next page of tag collection groups . If null, the response is the last page of tag collection groups .
prevPageLink string
The endpoint to call the previous page of tag collection groups. If null, the response is the first page of tag collection groups .
response array
Contains the rest of the response.
id integer
The tag collection group’s unique identifier.
reference string
The tag collection group’s unique reference code, which is also its name.
href string
The endpoint to call the tag collection group’s information, such as /api/v2/TagCollectionGroup/{id} where {id} is the tag collection groups’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 collection group information
Send a request to the endpoint to retrieve information for a specific tag collection group 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/TagCollectionGroup/{id} |
Returns information for the specified tag collection group, where {id} is the tag collection group’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": [
{
"subject": {
"id": 1,
"reference": "Subject1"
},
"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"
}
],
"subCollections": [
{
"id": 2,
"reference": "Subcollection Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/2"
}
],
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/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 collection groups there are in total. This is null because the information retrieved is for a specific tag collection group.
top integer
Details number of tag collection groups returned in the response. This is null because the information retrieved is for a specific tag collection group.
skip integer
Details how many tag collection groups were skipped to display those in the response. This is null because the information retrieved is for a specific tag collection group.
pageCount integer
Details how many pages of tag collection groups there are. This is null because the information retrieved is for a specific tag collection group.
nextPageLink string
The endpoint to call the next page of tag collection groups. This is null because the information retrieved is for a specific tag collection group.
prevPageLink string
The endpoint to call the previous page of tag collection groups. This is null because the information retrieved is for a specific tag collection group.
response array
Contains the rest of the response.
subject object
Contains the subject that the tag collection group is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
tagGroups array
Contains the information of the tag groups in the tag collection group.
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.
subCollections array
Contains any subcollection groups in the tag collection group. A subcollection group can be associated with a tag collection and contains multiple subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/id integer
The subcollection group’s unique identifier.
subCollections/reference string
The subcollection group’s unique reference code, which is also its name.
subCollections/href string
The endpoint to call the subcollection group’s information, such as /api/v2/TagCollectionGroup/{id} where {id} is the subcollection group’s unique identifier.
id integer
The tag collection group’s unique identifier.
reference string
The tag collection group’s unique reference code, which is also its name.
href string
The endpoint to call the tag collection group’s information, such as /api/v2/TagCollectionGroup/{id} where {id} is the tag collection group’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 collection group
Send a request to the endpoint to create a tag collection group.
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 collection group.
{
"subject": {
"reference": "Subject1"
},
"tagGroups": [
{
"id": 1
},
{
"id": 2
},
{
"id": 3
}
],
"reference": "Tag Collection Group 1"
}Request body schema
The request body schema contains a description of every property that can be passed with this endpoint.
subject object mandatory
Contains the subject that the tag collection group is in.
subject/id integer
The subject’s unique identifier.
subject/reference string
The subject’s unique reference code.
tagGroups array mandatory
Contains the information of any tag groups in the tag collection group.
tagGroups/id integer
The tag group’s unique identifier.
subCollections array optional
Assigns a subcollection group to the tag collection group. A subcollection group can be associated with a tag collection and contains multiple subcollections. Subcollections can be used to store additional information associated with its parent tag collection.
subCollections/id integer
The subcollection group’s unique identifier.
subCollections/reference string
The subcollection group’s unique reference code, which is also its name.
reference string mandatory
The tag collection group’s unique reference code, which is also its name.
Sample response
If successful, the HTTP status code will be 200 and the response body will contain the new tag collection group’s details.
{
"id": 1,
"reference": "Tag Collection Group 1",
"href": "https://{your Surpass instance}.surpass.com/api/v2/TagCollectionGroup/1",
"errors": null
}Deleting a tag collection group
Send a request to the endpoint to delete a specific tag collection group. 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/TagCollectionGroup/{id} |
Deletes specified tag collection group, where {id} is the tag collection group’s unique identifier. |
Sample response
If successful, the HTTP status code will be 200 and the response body will confirm the tag collection group 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/TagCollectionGroup?$skip={skip} query parameter, where {skip} is a number that should not exceed the total number of responses. |
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: