TagCollectionGroup OAPI

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 /oapi/TagCollectionGroup?fieldsNames=tagGroups would include the tag collection group’s tag groups in the response.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
fieldsNames	query OPTIONAL	`/oapi/TagCollectionGroup?fieldsNames={fieldsNames}`	Includes additional properties in the response not returned as standard, where `{fieldsNames}` is one of the following properties returned when retrieving information for a specific item: `tagGroups`, `collectionTemplates`, `children`.
filter	query OPTIONAL	`/oapi/TagCollectionGroup?filter={filter} {operator} {value}`	Filters results, searching for an exact match or for the data to contain a defined value. For an exact match: `{filter}` is one of `id`, `subject.id`, `subject.reference`, `subject.name`, `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. For a greater than query: `{filter}` is `id`, `subject.id`; `{operator}` is `ge` (greater than); and `{value}` is the integer the filter looks for more than in the request. For a less than query: `{filter}` is `id`, `subject.id`; `{operator}` is `le` (less than); and `{value}` is the integer the filter looks for less than in the request. For a contains query: `{filter}` is one of `id`, `reference`, `subject.name`, `subject.reference`; `{operator}` is `contains`; and `{value}` is the string or integer the filter query looks for an exact match for in the request.
filterGrouping	query OPTIONAL	`/oapi/TagCollectionGroup?filter={filter} {operator} {value}&filter={filter} {operator} {value}&filterGrouping={integer} {operator} {integer}`	Used to create different Boolean combinations when multiple properties are joined within a filter query parameter. See filter above. Each `{integer}` represents a respective filter starting at `0`, which are then combined using an `AND` or `OR` Boolean `{operator}`. EXAMPLE: The endpoint `/oapi/TagCollectionGroup?filter=id le 10&filter=subject.id ge 10&filterGrouping=0 OR 1` would return both tag collection groups with a unique identifier less than 10 (`0`) and those with their subject’s unique identifier being greater than 10 (`1`). TIP: More than two filter parameters can be combined, for example you might group three filters as follows: `0 AND 1 OR 2`.
orderBy	query OPTIONAL	`/oapi/TagCollectionGroup?orderBy=fieldName={fieldName}`	Determines order of results, where `{fieldName}` is `id.`
take	query OPTIONAL	`/oapi/TagCollectionGroup?take={take}`	Defines number of responses to return when paging a response, where `{take}` is a number between 1 and 100.
skip	query OPTIONAL	`/oapi/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.

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 /oapi/TagCollectionGroup?$take=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": 39,
    "top": 5,
    "skip": 0,
    "totalPages": 8,
    "nextPageLink": "https://{your Surpass instance}.surpass.com:443/oapi/TagCollectionGroup?Skip=5&Take=5",
    "previousPageLink": null,
    "results": [
        {
            "id": 1,
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
            },
            "reference": "Tag Collection Group 1"
        },
        {
            "id": 2,
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
            },
            "reference": "Tag Collection Group 2"
        },
        {
            "id": 3,
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
            },
            "reference": "Tag Collection Group 3"
        },
        {
            "id": 4,
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
            },
            "reference": "Tag Collection Group 4"
        },
        {
            "id": 5,
            "subject": {
                "id": 1,
                "reference": "Subject1",
                "name": "Geography Subject",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
            },
            "reference": "Tag Collection Group 5"
        }
    ],
    "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 groups there are in total.

top integer

Details number of tag groups returned in the response.

skip integer

Details how many tag groups were skipped to display those in the response.

totalPages integer

Details how many pages of tag groups there are.

nextPageLink string

The endpoint to call the next page of tag groups. If null, the response is the last page of tag groups.

previousPageLink string

The endpoint to call the previous page of tag groups . If null, the response is the first page of tag groups.

results array

Contains the rest of the response.

id integer

The tag group’s unique identifier.

subject object

Contains the subject that the tag group is in.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

subject/name string

The subject’s name.

subject/href string

The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.

reference string

The tag collection group’s unique reference code, which is also its name in Surpass.

errors string

Information about any errors that occurred during the request.

serverTimeZone enumeration

The timezone of the server sending the response.

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	path OPTIONAL	`/oapi/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.

{
    "response": {
        "id": 1,
        "reference": "Tag Collection Group 1",
        "tagGroups": [
            {
                "id": 1,
                "name": "Knowledge of European Geography",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
            }
        ],
        "collectionTemplates": null,
        "subject": {
            "id": 1,
            "reference": "Subject1",
            "name": "Geography Subject",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
        },
        "children": []
    },
    "serverTimeZone": "GMT Standard Time"
}

Response schema

The response schema contains a description of every property that can be returned for this endpoint.

response object

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 in Surpass.

tagGroups array

Contains the information of any tag groups in the tag collection group.

NOTE: If the tag collection group contains multiple tag groups, a separate object is returned for each tag group.

tagGroups/id integer

The tag group’s unique identifier.

tagGroups/name string

The tag group’s name.

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.

collectionTemplates array

Contains the information of any tag collection templates for the tag collection group.

NOTE: If the tag collection group contains multiple tag collection templates, a separate object is returned for each tag collection template.

collectionTemplates/name string

The tag collection template’s name.

collectionTemplates/id integer

The tag collection template’s unique identifier.

collectionTemplates/tags array

Contains the tag collection template’s tag groups and values.

NOTE: If the tag collection template contains multiple tag groups, a separate object is returned for each tag group and value.

collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

collectionTemplates/tags/tagGroup/name string

The tag group’s name.

collectionTemplates/tags/tagValue object

Contains the tag value’s information.

collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

collectionTemplates/tags/tagValue/name string

The tag value’s name.

collectionTemplates/tags/id integer

The tag group and tag value combination’s unique identifier.

subject object

Contains the subject that the tag collection group is in.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

subject/name string

The subject’s name.

subject/href string

The endpoint to call the subject’s information, such as /api/v2/Subject?reference={reference} where {reference} is the subject’s unique reference code.

children array

Contains the information of any subcollection groups for 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.

children/id integer

The subcollection group’s unique identifier.

children/reference string

The subcollection group’s unique reference code, which is also its name in Surpass.

children/tagGroups array

Contains the subcollection group’s tag groups

NOTE: If the subcollection group contains multiple tag groups, a separate object is returned for each tag group.

children/tagGroups/id integer

The tag group’s unique identifier.

children/tagGroups/name string

The tag group’s name.

children/tagGroups/href object

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

children/collectionTemplates array

Contains the information of any subcollection templates for the subcollection group.

NOTE: If the subcollection group contains multiple subcollection templates, a separate object is returned for each subcollection template.

children/collectionTemplates/name string

The subcollection template’s name.

children/collectionTemplates/id integer

The subcollection template’s unique identifier.

children/collectionTemplates/tags array

Contains the subcollection template’s tag groups and values.

NOTE: If the subcollection template contains multiple tag groups, a separate object is returned for each tag group and value.

children/collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

children/collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

children/collectionTemplates/tags/tagGroup/name string

The tag group’s name.

children/collectionTemplates/tags/tagValue object

Contains the tag value’s information.

children/collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

children/collectionTemplates/tags/tagValue/name string

The tag value’s name.

children/collectionTemplates/tags/id integer

The tag group and tag value combination’s unique identifier.

serverTimeZone enumeration

The timezone of the server sending the response.

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).

Sample request

The following request contains the minimum required request body to create a tag collection group.

{
  "tagGroups": [
    "Tag Group 1"
  ],
  "reference": "Tag Collection Group 1",
  "subject": {
    "reference": "Subject1"
  }
}

EXAMPLE: In this sample request, a tag collection group called ‘Tag Collection Group 1’ containing tag group ‘Tag Group 1’ is created within ‘Subject1’.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

tagGroups array mandatory

Contains the information of any tag groups in the tag collection group, using their name. Multiple tag groups can be added separated by commas.

IMPORTANT: Tag groups assigned to tag collections have to be single tag groups with the isCollectable property set to true. For more information, read TagGroup OAPI.

reference string mandatory

The tag collection group’s unique reference code, which is also its name in Surpass.

collectionTemplates array optional

Contains the information of any tag collection templates for the tag collection group.

NOTE: If the tag collection group contains multiple tag collection templates, pass a separate object for each tag collection template.

collectionTemplates/name string

The tag collection template’s name.

collectionTemplates/tags array

Contains the tag collection template’s tag groups and values.

IMPORTANT: Tag groups assigned to tag collections have to be single tag groups with the isCollectable property set to true. For more information, read TagGroup OAPI.

collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

collectionTemplates/tags/tagGroup/name string

The tag group’s name.

collectionTemplates/tags/tagValue object

Contains the tag value’s information.

collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

collectionTemplates/tags/tagValue/name string

The tag value’s name.

subject object mandatory

Contains the subject that the tag collection group is in.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

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

children/reference string

The subcollection group’s unique reference code, which is also its name in Surpass.

children/collectionTemplates array

Contains the information of any subcollection templates for the subcollection group.

NOTE: If the subcollection group contains multiple subcollection templates, pass a separate object for each subcollection template.

children/collectionTemplates/name string

The subcollection template’s name.

children/collectionTemplates/tags array

Contains the subcollection template’s tag groups and values.

NOTE: If the subcollection template contains multiple tag groups, pass a separate object for each tag group and value.

children/collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

children/collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

children/collectionTemplates/tags/tagGroup/name string

The tag group’s name.

children/collectionTemplates/tags/tagValue object

Contains the tag value’s information.

children/collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

children/collectionTemplates/tags/tagValue/name string

The tag value’s 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.

{
    "response": 1,
    "serverTimeZone": "GMT Standard Time"
}

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
content-type	header MANDATORY	`application/json`	Determines data format of the request (JSON).
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`	Determines data format of the response (JSON).
id	query MANDATORY	`/oapi/TagCollectionGroup?id={id}`	Updates specified tag collection group, where `{id}` is the tag collection group’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 group. Refer to the request body schema for all properties that can be updated.

{
    "reference": "Tag Collection Group 2"
}

EXAMPLE: In this sample request, the tag collection group is renamed to ‘Tag Collection Group 2’.

Request body schema

The request body schema contains a description of every property that can be passed with this endpoint.

tagGroups array

Contains the information of any tag groups in the tag collection group, using their name. Multiple tag groups can be added separated by commas.

IMPORTANT: Tag groups assigned to tag collections have to be single tag groups with the isCollectable property set to true. For more information, read TagGroup OAPI.

reference string

The tag collection group’s unique reference code, which is also its name in Surpass.

collectionTemplates array

Contains the information of any tag collection templates for the tag collection group.

NOTE: If the tag collection group contains multiple tag collection templates, pass a separate object for each tag collection template.

collectionTemplates/name string

The tag collection template’s name.

collectionTemplates/tags array

Contains the tag collection template’s tag groups and values.

IMPORTANT: Tag groups assigned to tag collections have to be single tag groups with the isCollectable property set to true. For more information, read TagGroup OAPI.

collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

collectionTemplates/tags/tagGroup/name string

The tag group’s name.

collectionTemplates/tags/tagValue object

Contains the tag value’s information.

collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

collectionTemplates/tags/tagValue/name string

The tag value’s name.

subject object

Contains the subject that the tag collection group is in.

subject/id integer

The subject’s unique identifier.

NOTE: The subject/id returned by the Surpass OAPI is from a different database to the one returned by the Surpass API v2; these values may be in sync, but that might not always be the case. If you are receiving different identifiers for the same subject from the OAPI and API v2, you can use subject/reference to reconcile your subject's properties instead.

subject/reference string

The subject’s unique reference code.

children array

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.

children/reference string

The subcollection group’s unique reference code, which is also its name in Surpass.

children/collectionTemplates array

Contains the information of any subcollection templates for the subcollection group.

NOTE: If the subcollection group contains multiple subcollection templates, pass a separate object for each subcollection template.

children/collectionTemplates/name string

The subcollection template’s name.

children/collectionTemplates/tags array

Contains the subcollection template’s tag groups and values.

NOTE: If the subcollection template contains multiple tag groups and values, pass a separate object for each tag group and value combination.

children/collectionTemplates/tags/tagGroup object

Contains the tag group’s information.

children/collectionTemplates/tags/tagGroup/id integer

The tag group’s unique identifier.

children/collectionTemplates/tags/tagGroup/name string

The tag group’s name.

children/collectionTemplates/tags/tagValue object

Contains the tag value’s information.

children/collectionTemplates/tags/tagValue/id integer

The tag value’s unique identifier.

children/collectionTemplates/tags/tagValue/name string

The tag value’s name.

Sample response

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

{
    "response": {
        "id": 1,
        "reference": "Tag Collection Group 2",
        "tagGroups": [
            {
                "id": 1,
                "name": "Knowledge of European Geography",
                "href": "https://{your Surpass instance}.surpass.com/api/v2/TagGroup/1"
            }
        ],
        "collectionTemplates": null,
        "subject": {
            "id": 1,
            "reference": "Subject1",
            "name": "Geography Subject",
            "href": "https://{your Surpass instance}.surpass.com/api/v2/Subject?reference=Subject1"
        },
        "children": []
    },
    "serverTimeZone": "GMT Standard Time"
}

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.

NOTE: An authorization header is mandatory, but the required input may vary. Read Connecting to the Surpass OAPI for more information on authentication and authorisation.

Name	Parameter	Input	Description
authorization	header OPTIONAL	`Basic {credentials}`	Basic authentication details must be passed to authorise the user’s request, where `{credentials}` is a Base64 encoded `username:password` string.
authorization	header OPTIONAL	`Bearer {token}`	A bearer token must be passed to authorise the user’s request, where `{token}` is a JWT (JSON web token).
accept	header OPTIONAL	`application/json`	Determines data format of the response (JSON).
id	query MANDATORY	`/oapi/TagCollectionGroup?id={id}`	Deletes specified tag collection group, where `{id}` is the tag collection group’s unique identifier.

Code	Description
400	Indicates one of the following issues: There is an issue with the query parameters. Tag collection group cannot be created. Tag collection group cannot be updated.
401	The request has been sent by an unauthorised user.
403	Tag collection group cannot be accessed.
404	Tag collection group does not exist.

In This Article

Listing tag collection groups

Parameters

Sample response

Response schema

Retrieving tag collection group information

Parameters

Sample response

Response schema

Creating a tag collection group

Parameters

Sample request

Request body schema

Sample response

Updating a tag collection group

Parameters

Sample request

Request body schema

Sample response

Deleting a tag collection group

Parameters

Sample response

Error Codes

Further reading

About the site