Tag Groups API v2 

In Evance, tags are a flexible way to classify and organize content across various resource types, such as Pages and Products. However, before you can assign tags to a resource, you must first define a Tag Group that is scoped to that specific resource type.

What is a Tag Group?

A Tag Group is a container for a set of tags and determines which resources those tags can be applied to. For example, if you want to tag your blog posts, you’ll need to create at least one Tag Group scoped specifically to the Page type (used for blog posts in Evance). Without a Tag Group, tags cannot be applied to that resource.

Most websites use a general-purpose Tag Group simply called "Tag", but you are not limited to just one.

Multiple Tag Groups per resource

Evance allows each resource to be associated with multiple Tag Groups. This provides greater flexibility for organizing content in different ways. For example, a blog post might be tagged under:

  • A Topic Tag Group could contain Tags such as Technology, Lifestyle, Health
  • A Sector Tag Group could contain Tags such as Education, Retail, Manufacturing

This structure allows developers and content managers to filter, sort, and present tagged content in more meaningful ways across a website.

Scopes

Access to the Tag Groups API requires that the client have the following scopes granted:

  • content - Permits write access to add, update or remove tag groups.
  • content.readonly - Read only access to search or get tag group data.

Object structure

id read-only
The unique ID for the Tag Group (unsigned 64-bit integer).
alias
This is an alternative identifier for the Tag Group. Since the alias is used by resources (e.g. Page) as an object property, the group’s alias has the following restrictions:
  • a-z - lowercase
  • 0-9 - numbers
  • _ - underscores may only appear mid string
  • - - dashes may only appear mid string
  • Maximum of 45 characters

For example, a generic tag group could have an alias of tag or default.

If an alias is not supplied when creating a tag group, Evance will attempt to create one. However, we recommend setting the alias manually.
title required
The title of your tag group indicates the topic of tags associated with it. A generic tag group might have a title of “Tags”. Maximum of 120 characters.
description
The topic description is optional, but allows you to attach deeper meaning to your tags. Usage of your tag group’s description varies per Theme. String - maximum of 255 characters.
scopes
An array of strings representing the resources the tag group is applicable to. Requires at least one of the following:
  • Contact
  • Page
  • Product
createdOn
The datetime in ISO-8601 format when the object was created (e.g. 2024-07-09T17:53:55+01:00).
createdBy
An integer representing the Contact ID who created the object. This may be set to null if the object was created by an App or via import.
modifiedOn
The datetime the object was last modified in ISO-8601 format (e.g. 2024-07-09T17:53:55+01:00)
modifiedBy
An integer representing the Contact ID of the last user to modify the object.

JSON example

{
  "id": 4684,
  "alias": "tags",
  "title": "Tags",
  "description": null,
  "scopes": ["Page"],
  "createdOn": "2019-11-09T01:02:00+00:00",
  "createdBy": 213,
  "modifiedOn": "2019-11-09T01:02:00+00:00",
  "modifiedBy": 213
}

List/search Tag Groups

GET /api/v2/tag-groups.json

Get or search for one or more tag groups using a range of accepted query parameters:

alias:in
Filter results by a comma separated list of aliases.
id:in
Filter results by a comma separated list of IDs.
scope:in
Filter results by a comma separated list of scopes.

Example JSON response

Evance will return a JSON object containing the following properties:

{
    "success": true,
    "status": 200,
    "data": [
        {
          "id": 4684,
          "alias": "tags",
          "title": "Tags",
          "description": null,
          "scopes": ["Page"],
          "createdOn": "2019-11-09T01:02:00+00:00",
          "createdBy": 213,
          "modifiedOn": "2019-11-09T01:02:00+00:00",
          "modifiedBy": 213
        }
    ],
    "pagination": {
        "page": 1,
        "limit": 100,
        "total": 1,
        "totalPages": 1
    },
    "links": {
        "self": "https://examples.evance.me/api/v2/tag-groups.json",
        "previous": null,
        "next": null
    }
}

Get a single Tag Group

GET /api/v2/tag-groups/{id}.json

Retrieve a single Tag Group using its ID.

{
    "success": true,
    "status": 200,
    "data": {
      "id", 63456,
      "alias": "tag", 
      "title": "Tags",
      "description": null,
      "scopes": [
        "Page"
      ],
      "createdOn": "2025-01-19T16:45:58+00:00",
      "createdBy": 97043,
      "modifiedOn": "2025-01-19T16:45:58+00:00",
      "modifiedBy": 97043
    }
}

Add a Tag Group

POST /api/v2/tag-groups.json

Adding a new Tag Group has a minimum requirement of title and scopes, but we recommend also supplying the alias.  POST JSON to this resource within a data object:

{
    "data": {
      "alias": "tag", 
      "title": "Tags",
      "scopes": [
        "Page"
      ]
    }
}

Update a Tag Group

PUT /api/v2/tag-groups/{id}.json

Updating a Tag Group by its ID requires you to PUT JSON to this resource within a data object:

URL parameters

id required
The ID of your Tag Group object supplied in the URL.

Request body

You are not required to supply the full object. For example, you may just wish to update the object's description:
{
    "data": {
      "description": "Tagged by topic"
}

Delete a Tag Group

DELETE /api/v2/tag-groups/{id}.json

Deleting a Tag Group by its ID does not require a body. Removing a Tag Group will remove all associated tags.

URL parameters

id required
The ID of your Tag Group object supplied in the URL.

Tagging resources with Tag Groups

Managing tags within tag groups has a common pattern across resources and utilises the tag group's alias. The character requirements for alias means we’re able to use it as a sub-property of a resource’s tags property.

{
    "data": {
    "tags": {
        "${alias}": string[]
    }
}

Example for a Page resource

{
  "data": {
    "id": 633286,
    ...
    "tags": {
      "topics": ["Technology", "Lifestyle", "Health"],
      "sectors": ["Hospitality", "Retail"]
    }
  }
}

This would require two Tag Groups with aliases topics and sectors, each scoped to the Page resource. 

The groups must already exist to assign tags.