Health Tags

Health Tags let your application track User-generated health context such as behaviors, symptoms, habits, or other daily observations. The Health Tags API has two distinct workflows: managing the tag library for your organization and supporting User tag selection and check-ins.

tag

Manage Health Tags

Create, update, list, and soft-delete custom tag definitions. See Managing Health Tags.

calendar-check

Use Health Tags

Let Users select tags from the library, write daily check-ins, and read check-in history. See Using Health Tags.

How Health Tags Work

Keep three related concepts separate.

Concept	What It Means
Tag library	InsideTracker-provided base tags plus custom tags your organization creates.
Available tags	The library entries available to the authenticated User. The API Reference also describes these as visible tags. List endpoints return these entries and can filter them with `tagSet`.
User's selected tags	The subset of available tags that a User has chosen to track. Selection controls the User's tracking choices; it does not determine whether a tag is available for check-ins.

For example, your organization can create a custom Morning walk tag and make it available through the customer tag list. A User can select it for tracking, and your application can record daily check-ins using the tag ID returned by the API.

Where This Fits

Health Tags are a user-generated health data flow. They help your application capture day-by-day context that can be displayed alongside other User health information.

The API surface is split by actor:

Management endpoints manage the tag library and categories for your organization.
Customer endpoints return selectable library entries, User selection state, and check-ins for an authenticated User.

Choose A Workflow

Workflow	Use When	Token Context	Guide
Tag library management	You need to create, update, list, or delete custom tags.	Service-level token with `health-tags` scope.	Managing Health Tags
User tag usage	You need to show selectable tags to a User, let the User select tags, or record check-ins.	Customer token with `basic` scope.	Using Health Tags

Shared Concepts

Several list endpoints accept a tagSet query parameter.

Value	Description
`BASE`	InsideTracker-owned tags.
`CUSTOM`	Custom tags available to the User 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.

Store tag IDs returned by the API. User tag usage workflows use returned tag IDs for selection and check-ins.

Endpoint Groups

Group	Endpoints	Guide
Tag library management	`GET/POST/PUT/DELETE /health-tags/partner/v1/tags` and `GET /health-tags/partner/v1/tag-categories`	Managing Health Tags
User tag usage	`GET/POST/DELETE /health-tags/customer/v1/tags`, `PUT /health-tags/customer/v1/check-ins`, and `GET /health-tags/customer/v1/check-ins-with-refs`	Using Health Tags