Using Health Tags

Use the customer Health Tags endpoints to show selectable tags from the tag library to a User, store the tags they select for tracking, write daily check-ins, and read check-in history.

Where This Fits

Using Health Tags is a customer-level workflow. It starts after your application has a customer-level token for the User. The customer tag list endpoint returns the tags available to the User: base InsideTracker tags and, when requested, custom tags from your organization.

The API describes tags returned for the authenticated User as visible tags. Selected tags are the subset of those available tags that the User has chosen to track. Visibility and selection are separate states.

For custom tag definition management, use Managing Health Tags.

Before You Begin

You need:

A customer token with the basic scope.
A decision about which tag set to offer: BASE, CUSTOM, or COMBINED.
The tag IDs returned by the customer tag list endpoint.
Dates formatted as YYYY-MM-DD.

Usage Tasks

The customer endpoints support several tag-usage tasks.

list

Show selectable tags

Fetch tag options from the library and show current selection state.

mouse-pointer-click

Manage tracking choices

Select or deselect tags when the User changes what they want to track.

calendar-check

Record check-ins

Write, update, or remove daily values for tags available to the User.

history

Read check-in history

Retrieve check-ins and tag metadata for timelines, trend views, or reporting.

Common Paths

Task	Typical Steps
Show selectable tags	Fetch tag options from the library with the tag set your experience should offer, then render them grouped by category.
Update tracking choices	Use the returned tag ID to select or deselect a tag option.
Record a daily check-in	Use the returned tag ID, check-in date, and boolean value to store the User's response.
Remove a daily check-in	Send `checkInValue: null` for the tag and date that should be cleared.
Read check-in history	Request an inclusive date range of 90 days or less.

Endpoint Overview

Step	Endpoint	Purpose
List selectable tags	`GET /health-tags/customer/v1/tags`	Returns tag options grouped by category, with User selection state.
Select tag	`POST /health-tags/customer/v1/tags/{tagId}`	Adds a tag option to the User's tracking set.
Deselect tag	`DELETE /health-tags/customer/v1/tags/{tagId}`	Removes a tag from the User's tracking set.
Write check-ins	`PUT /health-tags/customer/v1/check-ins`	Creates, updates, or deletes daily check-ins.
Read check-ins	`GET /health-tags/customer/v1/check-ins-with-refs`	Returns check-ins and tag metadata for a date range.

List Selectable Tags

Fetch tag options from the library and use the selected field to show which tags are already in the User's tracking set.

GET /health-tags/customer/v1/tags?tagSet=COMBINED

Query parameters:

Parameter	Required	Default	Use
`tagSet`	No	`BASE`	Selects which source of tags to return as selectable options.

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.

Use COMBINED when selectable options should include both InsideTracker base tags and custom tags.

Select Or Deselect Tags

To select or deselect a tag, call the customer tag endpoint with a tag ID returned by the selectable tag list.

POST /health-tags/customer/v1/tags/BASE_HIKING

DELETE /health-tags/customer/v1/tags/BASE_HIKING

Selecting or deselecting the same tag option repeatedly is safe. A selected tag becomes part of the User's tracking set.

Write Check-Ins

Use the check-in write endpoint to create, update, or remove a daily value.

PUT /health-tags/customer/v1/check-ins
Content-Type: application/json

[
  {
    "tagId": "BASE_HIKING",
    "checkInDate": "YYYY-MM-DD",
    "checkInValue": true
  }
]

Check-in rules:

tagId must identify a tag available to the authenticated User.
checkInDate must use YYYY-MM-DD.
Check-ins can be edited only within the allowed one-week window.
checkInValue: true or false stores the value.
checkInValue: null removes the tag's check-in for that date.

Handle Common Outcomes

Selecting or deselecting the same tag option repeatedly is safe, so your application can treat repeated selection changes as already applied.

If a check-in write fails because the date is outside the allowed one-week window, keep earlier check-in history read-only and ask the User for a date that can still be edited.

If a check-in write fails because the tag is not available to the User, refresh the customer tag list and use a tag ID returned for the authenticated User.

Read Check-Ins

Use the check-in history endpoint to retrieve an inclusive date range with tag metadata.

GET /health-tags/customer/v1/check-ins-with-refs?startDate={startDate}&endDate={endDate}

Rules for check-in history:

startDate and endDate are required.
startDate cannot be after endDate.
The requested range cannot exceed 90 days.
Every date in the range appears in the response data, including dates with no check-ins.
Tag metadata includes selected tags and tags that have responses in the range.
Returned tag metadata is sorted with selected tags first, then by case-insensitive title and ID.

Key Field Relationships

Field	Description
`categoryId`	Category identifier in the grouped customer tag response.
`categoryName`	Category display name.
`tags`	Tag options returned for the authenticated User in that category.
`tags[].id`	Selectable tag identifier. Use this as `{tagId}` when selecting or deselecting a tag.
`tags[].selected`	Whether the User has chosen the available tag for tracking.

Field	Description
`tagId`	Identifier for a tag available to the authenticated User. The tag does not need to be selected.
`checkInDate`	Date for the check-in in `YYYY-MM-DD` format.
`checkInValue`	Boolean value to store, or `null` to remove the check-in for that tag and date.

Field	Description
`tags`	Tag metadata required for the UI.
`data`	Object keyed by UTC calendar date in `YYYY-MM-DD` format.
`data[date]`	Array of check-ins for that date. Dates with no check-ins have an empty array.
`data[date][].tagId`	Tag identifier for the check-in entry.
`data[date][].set`	Stored check-in value for that tag on that date.
`data[date][].setAt`	Timestamp when the check-in value was stored.

Best Practices

Use returned tag IDs

Use tag IDs returned by the customer tag list endpoint for selection and check-in requests. Do not identify tags by title or by their position in a list response.

Prefer combined lists for User experiences

Use COMBINED when selectable options should include both InsideTracker base tags and custom tags.

Validate check-in dates

Check-ins can be edited only within the allowed one-week window, and history requests cannot exceed 90 days.

Implementation Checklist

Fetch selectable tags with the tag set your experience should offer.
Render tags grouped by category.
Reflect the selected state for each returned tag.
Use returned tag IDs for select and deselect requests.
Use tag IDs returned for the authenticated User in check-in requests.
Validate check-in dates before sending write requests.
Use 90-day or smaller windows when reading check-in history.

Using Health Tags

Using Health Tags

Where This Fits

Before You Begin

Usage Tasks

Common Paths

Endpoint Overview

List Selectable Tags

Select Or Deselect Tags

Write Check-Ins

Handle Common Outcomes

Read Check-Ins

Key Field Relationships

Best Practices

Implementation Checklist

Related API Reference

Related Topics