User Tags Migration Guide

Migrate from the old to the new user tags endpoint

Staffbase has introduced a new Tags API, which has replaced the old user tags endpoint under the User API. The Tags API is more scalable and returns tags used in user profiles in a more user-friendly format.

Staffbase recommends migrating to the new Tags API if you use the old user tags endpoint. To learn more, reach out to your Customer Success Manager.

In the following image you can see the documentation of the old user tags endpoint.

Old User Tags Documentation

Using the users/tags endpoint from the User API, you received the data in the following format:

1{
2   "total":4,
3   "data":[
4      {
5         "tag":"profile:example:aa"
6      },
7      {
8         "tag":"profile:example:ab"
9      },
10      {
11         "tag":"profile:shoesize:37"
12      },
13      {
14         "tag":"profile:shoesize:42"
15      }
16   ]
17}

In this response format, all tags are part of the data array. In the data array, each data element for a tag is referenced as the tag key.

The new Tags API endpoint provides you with the same information, but you get the response in the following format:

1{
2   "total":"2",
3   "cursor":"eyJzb3J0RmllbGRWYWx1ZSI6InByb2ZpbGU6dGVzdDA5MDYyMDIzOml0aGluayIsImxhc3RJZCI6IjY0ODJjY2FjYTUyZjRhNWMyZTYyN2ZjZiJ9",
4   "tags":[
5      {
6         "id":"00000020f51bb4362eee2a4d",
7         "value":"profile:example:aa"
8      },
9      {
10         "id":"00000020f51bb4362eee2a4f",
11         "value":"profile:example:ab"
12      }
13   ]
14}

In the Tags API, the tags are part of the tags array, and each element in the tags array is available within the value key. An example for accessing the first entry of the tag value using the old user/tags endpoint is as follows:

apiResponse.data[0].tag

An example for accessing the first entry of the tag value using the Tags API is as follows:

apiResponse.tags[0].value

The Tags API endpoint uses cursor-based pagination. To use the cursor for pagination, you need to set the cursor as a parameter to the query. You will get a maximum of 50 results in a call. The subsequent call will fetch the next 50 results until the tags array is empty.

/api/tags?cursor=eyJzb3J0RmllbGRWYWx1ZSI6InByb2ZpbGU6dGVzdDA5MDYyMDIzOml0aGluayIsImxhc3RJZCI6IjY0ODJjY2FjYTUyZjRhNWMyZTYyN2ZjZiJ9