Category Scores

Category Scores summarize a User's biomarker and physiomarker data into functional wellness categories. They help Users understand how groups of related markers connect to areas they can recognize in daily life, such as sleep, recovery, heart health, cognition, and metabolism.

In the API Reference, this surface appears under Biomarker Categories. Use the public marker-category reference endpoint to understand the available categories, then use the customer-level category-score endpoint to retrieve score state and contribution details for a User's results.

Where This Fits

Category Scores are available after the User has result data that can be grouped into health categories. This page focuses on retrieving and presenting the category-level output.

What Category Scores Are

Category Scores provide a high-level view of specific functional wellness areas. Instead of asking Users to interpret individual biomarkers in isolation, Category Scores group related biomarkers and physiomarkers into categories that are easier to connect to a User's lived experience.

This helps turn a long list of lab values into a smaller set of scoreable areas a User can understand, compare, and act on. A single biomarker can contribute to more than one category, so category scores should be treated as a separate output layer rather than a one-to-one grouping of markers.

The category reference endpoint returns the current category names, applicability, and descriptions. The current functional wellness categories are:

Category Scores are also useful across tests. Because the API returns scores by result, your application can show whether a functional area improved, declined, or stayed similar between tests. This gives Users a higher-level way to understand the impact of recommendations or habit changes without losing the marker-level detail underneath.

Use Category Scores as a dashboard-level signal. When a User needs more explanation, use the returned contribution fields and marker-level experiences to show which biomarkers or physiomarkers influenced the category.

Category Scores are displayed as numeric scores with a maximum of 100. Category reference ranges map scores to descriptive states such as OPTIMAL, GOOD, FAIR, and NEEDS_WORK.

Category Score presentation can combine several signals depending on the experience you are building:

Data Needed For This Output

The customer-level category-score endpoint requires a customer-level access token. Requests made without customer-level authentication will fail authorization.

Category Input Requirements

Each category has required markers and additional markers that can contribute when available. Required markers are inputs the category needs before the score can be determined. Average physiomarker inputs listed in this table are monthly averages. Use this table to understand input coverage, then retrieve the score, state, and contribution details from the API.

Workflow

Use Category Scores in two layers:

1. Retrieve category reference data.
2. Retrieve category scores for the User.
3. Match each returned categoryScores[].abbr to the reference items[].abbr.
4. Display the score, state, result date, and contribution details when your experience needs explanation.

Get Category Reference Data

Use the public reference endpoint to retrieve the available marker categories.

GET /api/public/references/marker-categories

The response includes an items array. Each category can include:

Use this endpoint instead of hard-coding category names, score ranges, or marker membership.

Get Category Scores

Use the customer-level endpoint to retrieve category scores grouped by result.

GET /api/customer/markers/categories-for-each-result
Authorization: Bearer {customer_access_token}

You can pass forLastResults when your application only needs a limited number of recent results.

GET /api/customer/markers/categories-for-each-result?forLastResults=3
Authorization: Bearer {customer_access_token}

The response includes an items array. Each item represents a result and includes category scores for that result.

{
  "items": [
    {
      "resultId": 19735,
      "testedAt": "2023-04-18T00:00:00-04:00",
      "categoryScores": [
        {
          "abbr": "HORMONE_BALANCE",
          "score": 51,
          "state": "CANNOT_DETERMINE",
          "contributions": [
            {
              "markerType": "blood",
              "markerAbbr": "hsCRP",
              "tested": true,
              "expired": false,
              "used": true,
              "optimizationState": "LOW",
              "score": 2.1
            }
          ]
        }
      ]
    }
  ]
}

Response Fields

Contribution entries can include marker identity, marker type, whether the marker was tested or used, freshness indicators, optimization state, and contribution score fields. Use these fields for explanatory UI, troubleshooting, or support views when your experience needs to show why a score looks the way it does.

Output Availability

Best Practices

Implementation Checklist

• You have a customer-level access token for the User.
• The User has published result data that can support category scores.
• Your application retrieves or stores category reference data for display names, descriptions, ranges, and marker membership.
• Your UI handles empty result lists and categories that cannot be determined.
• Your data model can connect category scores to resultId and testedAt.
• Your display handles contribution fields when they are present.

Related API Reference

• GET /api/public/references/marker-categories
• GET /api/customer/markers/categories-for-each-result
• Optional supporting content: GET /api/public/marker-categories/{categoryAbbr}/extra-information
• Related topic: Biomarker Reference Data
• Related topic: Optimal Zones