Managing Health Tags

Use the Health Tags management endpoints to manage custom tag definitions for your organization. Tags created with these endpoints are associated with your organization before Users select or check in with them.

Where This Fits

Managing Health Tags is an organization-level workflow. Use it when you need to define custom tags, organize tags by category, review available tag definitions, or remove a tag from future use.

For User selection and check-ins, use Using Health Tags.

Before You Begin

You need:

A service-level token with the appropriate health-tags scope.
The tag categories available to your organization.
A stable internal mapping from your product's tag concepts to the tag IDs returned by the API.

Management endpoint scopes differ by operation.

Operation	Required service-level token scope
List tag categories	`health-tags:r`
List tag definitions	`health-tags:r` and `health-tags:w`
Create, update, or delete tags	`health-tags:w`

Management Tasks

The management endpoints support several tag-management tasks.

list

Inspect available tags

List categories and tag definitions when you need to build or audit the catalog available to your application.

plus

Create custom tags

Add custom tags when the base catalog does not cover the User context you need to track.

pen

Update active tags

Change an active tag before Users have recorded check-ins for it.

Common Paths

Task	Typical Steps
Inspect available tags	Fetch categories, then list `BASE`, `CUSTOM`, or `COMBINED` tag definitions.
Add a custom tag	Fetch categories, create the tag with a valid `categoryId`, then store the returned `id`.
Change an active tag	Update title, description, or category before Users begin recording check-ins for the tag.
Retire a tag	Delete the active tag definition. Historical User responses are retained.

Endpoint Overview

Step	Endpoint	Purpose
List categories	`GET /health-tags/partner/v1/tag-categories`	Returns available tag categories.
List tags	`GET /health-tags/partner/v1/tags`	Returns non-deleted tag definitions for the requested source.
Create tag	`POST /health-tags/partner/v1/tags`	Creates an active custom tag.
Update tag	`PUT /health-tags/partner/v1/tags/{tagId}`	Updates an active custom tag.
Delete tag	`DELETE /health-tags/partner/v1/tags/{tagId}`	Soft-deletes an active custom tag.

List Categories And Tags

Fetch categories before creating tags so your application submits a valid categoryId.

GET /health-tags/partner/v1/tag-categories

Category query parameters:

Parameter	Required	Default	Use
`page`	No	`0`	Zero-based page index. Must be zero or greater.
`size`	No	`20`	Maximum number of categories per page. Must be greater than zero.

Use tagSet when listing tag definitions. Add categoryId, page, and size when you need to narrow or page through the tag library.

GET /health-tags/partner/v1/tags?tagSet=CUSTOM&categoryId=ACTIVITY&page=0&size=20

Tag list query parameters:

Parameter	Required	Default	Use
`tagSet`	No	`BASE`	Selects which source of tags to return.
`categoryId`	No	none	Filters tags to a single category. Omit it to return all categories.
`page`	No	`0`	Zero-based page index. Must be zero or greater.
`size`	No	`20`	Maximum number of tags per page. Must be greater than zero.

Value	Description
`BASE`	InsideTracker-owned tags.
`CUSTOM`	Custom tags available through your organization.
`COMBINED`	Base and custom tags together. When a custom tag matches a base tag by title, the custom tag replaces the base tag in the response.

Create Tags

Create custom tags after retrieving the available categories.

POST /health-tags/partner/v1/tags
Content-Type: application/json

{
  "key": "MORNING_WALK",
  "title": "Morning walk",
  "description": "User completed a morning walk.",
  "categoryId": "ACTIVITY"
}

Creation rules:

key must use uppercase letters, digits, and underscores.
title must be unique among your organization's active tags, ignoring case.
categoryId must refer to an existing tag category.
The resulting tag identifier must not already exist, including soft-deleted tags.
The returned tag ID is the value to store and use later.

The tag id returned by the API may differ from the key you submit. Store the returned id and use it for future tag selection, check-in, update, and delete requests.

Update Tags

Update an active tag before Users begin recording check-ins for it.

PUT /health-tags/partner/v1/tags/MORNING_WALK
Content-Type: application/json

{
  "title": "Morning walk",
  "description": "User completed a morning walk.",
  "categoryId": "ACTIVITY"
}

Update rules:

At least one request field must contain a non-blank value.
A supplied category must exist.
A supplied title must be unique among your organization's active tags, ignoring case.
Tags with any customer check-in response cannot be updated.

Handle Common Outcomes

If a tag update is rejected because User check-in responses already exist, do not keep retrying the same update. Leave the existing tag in place while you decide whether a replacement tag should be created for future use.

If tag creation fails because the resulting tag identifier is already in use, choose a new key. Soft-deleted tag identifiers cannot be reused.

Delete Tags

Deleting a tag soft-deletes the active tag definition. Historical User responses are retained.

DELETE /health-tags/partner/v1/tags/MORNING_WALK

Key Field Relationships

Field	Description
`id`	Category identifier. Use this as `categoryId` when creating or updating a tag.
`name`	Category display name.

Field	Description
`key`	Required suggested key. Maximum 50 characters. Only uppercase letters, digits, and underscores are allowed.
`title`	Required tag title. Maximum 50 characters.
`description`	Required tag description. Maximum 200 characters.
`categoryId`	Required identifier of an existing tag category.

Field	Description
`id`	Tag identifier returned by the API. Store this value for User selection and check-ins.
`title`	Tag title.
`description`	Tag description.
`category`	Category metadata for the tag.
`partnerId`	Identifier for the organization that owns the tag.

Best Practices

Store returned tag IDs

Store and reuse the tag IDs returned by the API. Do not reconstruct an ID from the submitted key or use the tag title as its canonical identifier.

Fetch categories before creation

Use category responses as the source for valid categoryId values in create and update requests.

Plan tag edits before User check-ins

Finalize title, description, and category choices before presenting a tag to Users. If check-in responses already exist, the API rejects the update.

Implementation Checklist

Fetch tag categories before creating custom tags.
Choose BASE, CUSTOM, or COMBINED when listing tags.
Create tags with uppercase key values.
Store returned tag IDs.
Finalize tag titles, descriptions, and categories before Users begin recording check-ins.
Treat deletion as a soft delete that retains historical responses.

Managing Health Tags

Managing Health Tags

Where This Fits

Before You Begin

Management Tasks

Common Paths

Endpoint Overview

List Categories And Tags

Create Tags

Update Tags

Handle Common Outcomes

Delete Tags

Key Field Relationships

Best Practices

Implementation Checklist

Related API Reference

Related Topics