API – Creating Tags and Tag Groups

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the folders one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Folder. These will be referenced as Client / Folder in all guides.

Creating a Tag

Tags are a great way to both add insightful metadata to a Product or group of Products as well as create a means of filtering Product’s when searching for Products. Tags are created on the Platform within a Client / Folder and are unique to this Client / Folder. This means the Tag “Woven” can only exist once in a Client / Folder but can be applied to every Product within if desired. This also means, however, that the Tag “Woven” must be created again in every Client / Folder that it is needed, as it cannot be applied to Products in another Client / Folder.

In addition to Product Tags, Configurators can have Tags applied to them. Configurator Tags share the Client / Folder Tag pool with Products, meaning the Tag “Woven” can be applied to both a Product and a Configurator. However, a Tag applied to a Configurator doesn’t automatically get added to the Products within the Configurator.

As with all endpoints in the Admin API, you must first complete the appropriate level of authentication for your account and generate a Refresh Token (Authentication guide).

Authentication Steps Summary

Log in using an Authentication Key or email / password.
- Returns an x-auth-token in the Response Headers.
Retrieve a list of Organizations and store the needed Organization’s UUID.
- Pass the x-auth-token from Step 1 in the Request Headers.
  
  1
  
  { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token }
- This step can be skipped if the Organization UUID is already stored locally.
Generate a Refresh Token for the Organization.
- Pass the x-auth-token from Step 1 in the Request Headers.
  
  1
  
  2
  
  3
  
  4
  
  {
  
  ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
  
  ‘organizationUuid’ : ‘string’
  
  }
- Returns the Refresh Token as the Response Header x-auth-token.
Retrieve a list of Clients / Folders and store the needed UUID.
- Pass the x-auth-token in the Request Headers.
- This step can be skipped if the Client / Folder UUID is already stored locally.
Generate a Refresh Token for the Client / Folder (Organization Admin / Owner users must skip this step).
- Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Client UUID’s.
  
  1
  
  2
  
  3
  
  4
  
  5
  
  {
  
  ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
  
  ‘organizationUuid’ : ‘string’,
  
  ‘clientUuid’ : ‘string’
  
  }
- Returns the Refresh Token as the Response Header x-auth-token.

To create a Tag, you should first check to verify the Tag doesn’t already exist within the Client / Folder. You can skip this and just move on if the request returns the Error message that the Tag already exists, however unless you are simply creating a batch of Tags and do not need the Tag UUID right away, it would be best to search the Tags first to retrieve the UUID of already created Tags for immediate use.

Method: POST
Endpoint: /v1/tags/search
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“clientUuid”: “string”,
“page”: 1,
“searchTerm”: “string”,
“size”: 10
}

Once you have confirmed the Tag you wish to create doesn’t already exist, you can simply make the following Request:

Method: POST
Endpoint: /v1/tags/create
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-client-uuid’,
‘name’ : ‘Some Tag’,
‘tagGroupUuid’ : ‘some-tag-group-uuid’
}

Only clientUuid and name are required for the Request Body. A successful request will return the newly created Tags UUID in the Response Body and can then be passed in the Request Body of a Product Creation request, Configurator Creation request, or simply stored locally to avoid having to make an API call to check on Tags and retrieve their UUID’s.

Tag Groups

Another Tag related feature are Tag Groups. Like Tags these are Client / Folder specific and act as a means of organizing your Tags. You can create a Tag Group and then create Tags related to this group, allowing you to then make an API call to retrieve the Tag Group with all Tags names and UUID’s returned, instead of needing to search for each Tag individually. Note: Tag Groups do not overwrite the restriction of each Tag existing once in a Client / Folder, the same Tag cannot be created or applied to multiple Tag Groups.

To retrieve Tag Groups, use the following endpoint:

Method: GET
Endpoint: /v1/tag-groups/clients/client-uuid
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Query Params: ‘page’, ‘size’
Example: https://api-platform.vntana.com/v1/tag-groups/clients/client-uuid?page=0&size=10

Please note, for this endpoint, the first page is actually 0 not 1, and page and size are required.

Tag Group Search Sample Response

A sample response from a successful Tag Group search:

{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “some-tag-group-uuid”,
“name”: “UNASSIGNED”,
“tags”: [
{
“uuid”: “tag-uuid-1”,
“name”: “Some Tag 1”
},
{
“uuid”: “tag-uuid-2”,
“name”: “Some Tag 2”
}
]
}
]
}
}

To create a Tag Group, use the following endpoint:

Method: POST
Endpoint: /v1/tag-groups/create
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
‘clientUuid’ : ‘some-uuid’,
‘name’ : ‘string’
}

Tag Groups are not required, any Tag created without specifying a Tag Group will be placed in the UNASSIGNED Tag Group which is the default of every Client / Folder.

Postman Collection

To test these processes, we’ve included two Postman collections, one to create a Tag and one to create a Tag Group. For both, you will need to set the various global variables in the Pre-request Script of the collection itself, and each can be run as either a full collection (simply select which endpoints you wish to run) or as individual endpoints. To run the endpoints individually you will have to activate the deactivated headers and make sure the necessary data is filled in for each endpoint. Additionally, for the Tag Group collection, the actual Tag Group creation endpoint will fail if a Tag Group already exists, so don’t be alarmed if that single endpoint fails. You can view our general guide on using Postman collections here.

Create Tags Collection

Create Tag Group Collection

Resources