Sample Response

{
  "total": 143,
  "biomarkers": [
    {
      "id": 21,
      "categoryId": 10,
      "isUnitless": false,
      "status": "N",
      "entries": [
        {
          "seid": "c7bdd15d-596c-475c-8e6c-e21ac98d0d4e",
          "sid": "b9efa122-ed77-4335-b324-60b49f786d16",
          "value": "18210.0",
          "originalValue": "18.21",
          "date": 1614733200,
          "originalUnitId": 9
        }
      ]
    }
  ],
  "refs": {
    "215": {
      "common": [
        0.1476,
        0.8116
      ],
      "optimal": [],
      "paidOptimal": [
        0.4021,
        0.8116
      ]
    }
  }
}

Profile Biomarkers

Endpoint URL:
https://sandbox-api.ornament.health/public/medical-data-api/v1.0/profile/biomarkers

HTTP Method:
GET

Parameters

Obligatory

Name	Type	Description
pid	string	User profile identifier.

Optional

Name	Type	Description
limit	integer	Limit number of records in the response.
skip	integer	Number of records to skip in the response.
search	string	Search query string.
abnormal	boolean	`TRUE` – only abnormal biomarkers, `FALSE` – only normal biomarkers.
dateFrom	integer	Start date/time (Unix timestamp). Use `0` for all time.
dateTo	integer	End date/time (Unix timestamp).

Response Structure

The response is a JSON file containing two types of objects:

biomarker objects – contain information about biomarkers used in scoring, including one or multiple entries sub-objects that describe recorded biomarker values.
ref objects – contain reference ranges for biomarkers recorded for this user profile.

Response Object Attributes

Root

Attribute	Type	Description
total	integer	Number of biomarkers included in the response.

biomarker

Attribute	Type	Description
id	integer	Identifier of the biomarker ( See reference)
categoryId	integer	Identifier of the biomarker’s category. ( See reference)
isUnitless	boolean	`TRUE` if the biomarker is unitless.
status	string	Biomarker status: `N = Normal (within reference range)`, `A = Abnormal (outside reference range)`.
entries	array	List of recorded values (see below).

biomarker.entries

Attribute	Type	Description
seid	string	Submission entry ID (line).
sid	string	Submission ID.
value	string	Biomarker’s value in default units.
originalValue	string	Biomarker’s value in original units.
date	integer	Date/time of the submission in Unix timestamp. For image-based submissions, the sample collection date/time from the report is used.
originalUnitId	integer	Identifier of the biomarker’s original unit.

ref

Each ref object corresponds to a biomarker ID and contains reference ranges calculated based on the user profile data (such as age and gender).

For example, in the response below, the reference ranges belong to biomarker ID 215.

"refs": { 
  "215": {
    "common": [
      0.1476,
      0.8116
    ],
    "optimal": [],
    "paidOptimal": [
      0.4021,
      0.8116
    ]
  }
}

Attribute	Type	Description
common	list	Reference range currently used for scoring purposes for this user profile (PID), based on age and gender.
optimal	list	Optimal (“healthy”) reference range. ⚠️ Note: Some biomarkers do not have optimal ranges set up.
paidOptimal	list	Same as optimal.

⚠️ Note:
All reference ranges are provided in default measurement units, so they can be converted into target units the same way as biomarker values.

Custom Reference Ranges

By default, Ornament uses its own collection of biomarker reference ranges.
There are two ways to override the default reference values:

B2B custom reference ranges
If a B2B user wishes to use their own reference ranges for certain biomarkers, Ornament can configure this.
- The B2B user should contact Ornament support and provide the list of custom reference range values.
- Once set up, the B2B user and all its linked profiles (PIDs) will use these custom reference ranges.
- These values take priority over Ornament’s default ranges.
Individual (PID) custom reference ranges
If an individual user (PID) linked to a B2B client sets up their own personal reference range for a biomarker in the Ornament app:
- This personal reference range has absolute priority.
- It overrides both Ornament’s default ranges and the B2B user’s custom ranges.

Priority Hierarchy

The priority order for a biomarker’s reference ranges is:

Top priority: User’s (PID) personal reference range (set up in the Ornament app).
Next priority: Custom reference range set up for the B2B user and its linked profiles.
Lowest priority: Ornament’s default reference range.

Converting Biomarker Values Between Different Measurement Units

This section explains how to convert biomarker values between measurement units using the default value stored in a user’s submission entry.

Example: Submission Entry from User Profile

{
  "id": 32,
  "categoryId": 17,
  "isUnitless": false,
  "status": "N",
  "entries": [
    {
      "seid": "213c6a47-eb38-4894-bb71-b9acd05ba74e",
      "sid": "ef6f69d3-fa72-4ca4-a1e0-10b2f577b6f7",
      "value": "12000.0",
      "originalValue": "12",
      "date": 1745798400,
      "originalUnitId": 26
    }
  ]
}

originalUnitId and originalValue – refer to the biomarker’s value as received from the lab report.

value – default converted value (used as the basis for conversions to other units).

Conversion Steps

1. Get Biomarker ID and Default Value

Use the Profile Biomarkers endpoint.

From the example above:

Biomarker ID = 32
Default value = 12000.0

2. Get Available Units and Conversion Factors

Use the Biomarkers endpoint to retrieve unit IDs and their associated unit factors.

Example response snippet for biomarker ID 32 (Homocysteine, blood):

{
  "id": 32,
  "title": "Homocysteine, blood",
  "unitsFactors": [
    [26, 1000.0],
    [30, 1000000.0],
    [62, 1000.0],
    [28, 73975.0],
    [29, 7397.5],
    [57, 7397.5]
  ],
  "isUnitless": false
}

Here:

26, 30, 62, etc. are unit IDs.
The second value in each pair is the unitFactor.

3. Get Unit Name

Use the Measurement Units endpoint to retrieve the unit name for a given unit ID.

Example response for unit ID 30:

{
  "id": 30,
  "title": "mmol/L",
  "synonymsString": "mmol/L",
  "valueType": 1
}

4. Apply Conversion Formula

To convert the biomarker’s default value into the target unit:

Converted Value = Default Value / UnitFactor

Example:
Convert Homocysteine (ID 32) from µmol/L (unitId 26) to mmol/L (unitId 30):

Default value = 12000.0
Unit factor (for mmol/L, ID 30) = 1000000.0

12000.0 / 1000000.0 = 0.012 mmol/L