Biomarkers V1.1

Time	Status	User Agent
Retrieving recent requests…

Use this method to retrieve the biomarker dictionary, including:

names
synonyms
categories
biomaterials
optional linked content
supported units and conversion factors

This method returns only thesaurus data as used in Ornament. It does not return actual digitized lab results. You can use this dictionary to interpret digitized data responses, for example to resolve biomarker IDs and understand their corresponding names, categories, and supported units.

Request body

{
  "lang": "EN"
}

Body parameters

Name	Type	Required	Description
`lang`	string	Yes	Language used for biomarker titles and synonyms. Supported values: `EN`,`DE`, `ES`, `PT`,`RU` `EN+ES` — English title, Spain and English synonyms. `EN` — English title, English synonyms. Example: `EN`.

Request example

curl --request POST \
  --url 'https://api.ornament.health/thesaurus-api/public/v1.1/biomarkers' \
  --header 'Content-Type: application/json' \
  --data '{
    "lang": "EN"
  }'

Response

Returns an object with updated metadata and the list of biomarkers.

Top-level response schema

Field	Type	Required	Description
`needToUpdate`	boolean	Yes	Indicates whether the client should refresh its cached dictionary.
`digest`	string	Yes	Dictionary version hash. Can be used to detect changes.
`biomarkers`	array of objects	Yes	List of biomarker definitions.

Notes

To check whether the biomarker list has changed, you can use the digest field returned by this method.

On the next request, send the previously received digest in the request body together with lang. If the biomarker dictionary has not changed, the response will contain needToUpdate: false, so you can keep using your cached version. If it has changed, the API will return the updated biomarker list together with a new digest value for future checks. For more details, see the Digest documentation.

Top-level response example

{
  "needToUpdate": true,
  "digest": "968C5841EA26D2E7B38FFE56FC828600ECA8CD27967303FF24BEDF661A8A4F4E",
  "biomarkers": [
    {
      "id": 0,
      "title": "Anion Gap",
      "synonyms": [
        {
          "title": "Agap",
          "language": "EN"
        }
      ],
      "possibleValueMax": 25000000.0,
      "possibleValueMin": 3000000.0,
      "isAllowAutounit": true,
      "biomaterialId": 1,
      "displayCategoryId": 16,
      "pregnancyCorrelation": 0,
      "sortOrder": 3505,
      "isPaid": true,
      "unitsFactors": [
        [27, 1000000.0],
        [30, 1000000.0]
      ],
      "isUnitless": false
    }
  ]
}

Biomarker object schema

Each element in the biomarkers array describes one biomarker.

Field	Type	Required	Description
`id`	integer	Yes	Unique biomarker identifier.
`title`	string	Yes	Biomarker display name in the requested language.
`synonyms`	array	Yes	Alternative names for matching and display.
`possibleValueMax`	number	No	Maximum supported value in the system default unit.
`possibleValueMin`	number	No	Minimum supported value in the system default unit.
`isAllowAutounit`	boolean	Yes	Whether automatic unit recognition / conversion is supported.
`biomaterialId`	integer	Yes	Identifier of the biomaterial associated with the biomarker.
`substanceId`	integer	No	Identifier of the related substance, when applicable.
`displayCategoryId`	integer	Yes	Category identifier for grouping. Matches category `id` from `/biomarker-categories`.
`pregnancyCorrelation`	integer	Yes	Pregnancy-related correlation flag used by the platform.
`sortOrder`	integer	No	Sort position for displaying biomarkers.
`isPaid`	boolean	Yes	Whether the biomarker is treated as premium in the Ornament platform.
`articleId`	integer	No	Identifier of an article or content record (Ornament wiki) associated with the biomarker.
`unitsFactors`	array of `[unitId, factor]` pairs	Yes	Supported units and their conversion factors relative to the default system unit.
`isUnitless`	boolean	Yes	Whether the biomarker does not require a unit.

`synonyms` object schema

Field	Type	Required	Description
`title`	string	Yes	Synonym text.
`language`	string	Yes	Synonym language.

`unitsFactors` schema

unitsFactors is an array of arrays:

[
  [unitId, factor]
]

Where:

Position	Type	Description
`0`	integer	Unit identifier.
`1`	number	Conversion factor for that unit.

Notes on `unitsFactors`

A biomarker may support multiple units.
Each supported unit is represented by its unitId.
The numeric factor is used to convert between the platform default unit and the target unit.
To resolve the unit name, symbol, or metadata, use the corresponding measurement units dictionary endpoint.

Example biomarker

{
  "id": 1,
  "title": "ALT",
  "synonyms": [
    {
      "title": "Alanine aminotransferase",
      "language": "EN"
    },
    {
      "title": "GPT",
      "language": "EN"
    },
    {
      "title": "Glutamic Pyruvate Transaminase",
      "language": "EN"
    }
  ],
  "possibleValueMax": 1500.0,
  "possibleValueMin": 0.0,
  "isAllowAutounit": true,
  "biomaterialId": 2,
  "displayCategoryId": 16,
  "pregnancyCorrelation": 0,
  "sortOrder": 3896,
  "isPaid": true,
  "articleId": 1,
  "unitsFactors": [
    [8, 1.0],
    [10, 60000000.0],
    [13, 60.0],
    [52, 1.0],
    [127, 0.06],
    [128, 0.06],
    [129, 60.0],
    [130, 1000.0],
    [131, 0.0166667],
    [132, 16.6667]
  ],
  "isUnitless": false
}