Units

Overview

All biomarker values submitted to the API must include a unit expressed in UCUM (Unified Code for Units of Measure) format. The platform stores and returns values using the unit you provide; no implicit normalization occurs on the response. Internally, units are converted to a preferred canonical unit for validation and QA processing, but this is intentionally transparent to the caller.

Preferred Units

Each biomarker has a preferred canonical unit. The preferred unit is listed in the full on the Biomarkers page. A subset is shown below for reference:

Compatible Units

You are not required to submit values in the preferred unit. Any unit that is dimensionally compatible with the preferred unit is accepted.

What "dimensionally compatible" means

Two units are dimensionally compatible if they measure the same physical quantity and can be converted to one another using a fixed conversion factor (they share the same dimension, such as mass/volume, length, or time).

For example, the preferred unit for IGF-1 is ng/mL. All of the following are dimensionally compatible and will be accepted:

• ug/dL (mass/volume, same dimension)
• ng/dL (mass/volume, same dimension)
• ug/mL (mass/volume, same dimension)

The following would not be accepted:

• mmol/L: requires knowledge of the analyte's molar mass to convert to a mass-based unit; this information is not available to the platform at conversion time
• IU/mL: biological activity units are not dimensionally interchangeable with mass/volume units without analyte-specific factors

Rule of thumb: if the conversion requires anything beyond a fixed numeric factor (such as molar mass or analyte-specific activity), the unit is not compatible.

UCUM Formatting Requirements

Submitted units must be valid UCUM expressions. A few common pitfalls:

Use UCUM annotations for non-standard quantities

Some biomarkers are measured in quantities that have no standard UCUM dimension (e.g. specific gravity, index values, cell counts). These must be expressed using UCUM annotations, which are curly-brace-delimited labels appended to the expression.

Graceful annotation handling

The platform will attempt to apply annotations automatically if a submitted unit is not recognized as valid UCUM. This is a best-effort conversion; there is no guarantee it will succeed. If the annotation-corrected unit still does not resolve to a compatible dimension, the entry will fail. It is strongly recommended to submit correctly annotated UCUM expressions rather than relying on this fallback.

International Units (IU) vs. Enzyme Units (U)

For enzyme biomarkers such as AST, ALT, GGT, and ALP, both U/L and IU/L appear in real lab data and are equivalent in the context of enzyme activity. In UCUM, however, IU formally denotes International Units, a biological activity measure used for vitamins, hormones, and vaccines, while U is the more precisely defined term for enzyme activity. Because the platform must canonicalize one, U/L is the preferred unit for enzyme biomarkers.

Some laboratory sources, notably Labcorp, report enzyme results as IU/L. The platform will attempt to interpret IU/L as U/L for enzyme biomarkers where this equivalence is known to apply. This is a best-effort correction. Clients should normalize IU/L to U/L for enzyme biomarkers before submitting, particularly when ingesting data from sources known to use this convention.

Unit Validation Failures

If a submitted unit is invalid or incompatible, the affected entry is marked as failed in the response payload. The failure is scoped to that entry only; the rest of the request is processed normally.

Failed entries will include a failure reason in the response. Common causes:

• Unit is not a valid UCUM expression and could not be resolved via annotation fallback
• Unit is dimensionally incompatible with the preferred unit for that biomarker (e.g. a molar concentration submitted for a mass-based biomarker)
• Unit is unrecognized entirely

Note: The exact structure of the failure payload is documented in the timeseries scoring reference.

Examples

Accepted: compatible mass/volume unit

{
  "code": "33863-3",
  "value": 0.112,
  "unit": "mg/dL"
}

mg/dL is dimensionally compatible with the preferred mg/L. The platform converts internally and returns the value in mg/dL as submitted.

Accepted: preferred unit

{
  "code": "29463-7",
  "value": 194.1,
  "unit": "[lb_av]"
}

Potentially Rejected: non-UCUM unit without annotation

{
  "code": "751-8",
  "value": 8000,
  "unit": "cells/uL"
}

cells/uL is not a valid UCUM expression, but is often returned from labs like Quest or Labcorp for cell count measurements. The platform will attempt to resolve it as {cells}/uL, but this is not guaranteed. Submit {cells}/uL directly to avoid failure.

Rejected: incompatible dimension (molar concentration)

{
  "code": "2839-9",
  "value": 116.5,
  "unit": "nmol/L"
}

nmol/L cannot be converted to ng/mL without the molar mass of the specific analyte. This entry will fail.