Result Formats

Vital’s API returns results in two different formats.

• PDF
• JSON

​

PDF Results

We return the raw results in PDF form, that we receive directly from our partner labs. This can be retrieved as follows:

curl --request GET \
     --url {{BASE_URL}}/v3/order/result/pdf \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/pdf' \
     --header 'x-vital-api-key: <your_api_key>' \

An example result:

​

JSON Results

We also return the parsed results in JSON format, so you can use them to generate your own forms.

These results are returned in a structured format, which you can find here.

​

Result Status

The status field can be one of the following:

1. ResultStatus.PARTIAL - The results are partial. Labs can return results before all biomarkers are available. Vital makes these results available to you as soon as we receive them, but does not send a webhook notification for partial results.

   This means that if you probe the API for results, you might get a partial result, even if there was no webhook for a labtest.update event.

   This is done due to the possibility of critical values in the results.

2. ResultStatus.FINAL - The results are complete. This means that all biomarkers are available, and the results are final. You will receive a labtest.update webhook notification for this event.

​

BiomarkerResult

A BiomarkerResult has the following definition:

name: str
slug: str
value: float  # deprecated
result: str
type: ResultType
unit: str | None
timestamp: datetime | None
notes: str | None
min_range_value: float | None
max_range_value: float | None
is_above_max_range: bool | None
is_below_min_range: bool | None
interpretation: str = Interpretation.NORMAL
loinc: str | None
loinc_slug: str | None

​

ResultType

Results can fall into one of the following categories:

1. ResultType.NUMERIC - A numeric result, e.g. 1.2

   In this case, the result field will be a string representation of the number, and the value field will be a float representation of the number.

2. ResultType.RANGE - A range result, e.g. <1.2

   In this case, the result field will be a string representation of the range value, and the value field will be -1.

   Note that you will also find the <1.2 value in the notes field.

   A range result will always be a value following the pattern ^([<>]=?\d*(\.\d+)?|(\d*(\.\d+)?-\d*(\.\d+)?))$.

3. ResultType.COMMENT - A text result, e.g. Positive

   In this case, the result field will be a string representation of the text, and the value field will be -1.

   Note that you will also find the Positive value in the notes field.

​

Interpretation

Interpretation is a string value that can be one of the following:

1. Interpretation.NORMAL - The result is within normal parameters.
2. Interpretation.ABNORMAL - The result is outside of normal parameters.
3. Interpretation.CRITICAL - The result is outside of critical parameters. In this case, refer to the critical values section.

​

Standardisation - LOINC

It’s possible to test the same biomarkers across different laboratories. For these to match, we use the LOINC standard.

In the BiomarkerResult object, you can see two fields loinc_slug and loinc. These fields refer to the LOINC standard. Customers should use this standard, so it’s possible to match results across different laboratories. You can expect that the slug field is what the laboratory returns to us - and the loinc_slug is the standardised version.

An example:

As you can see, the same biomarker HDL Cholesterol can have different slugs across different laboratories. However it’s represented by the same LOINC value.

​

Expected Results

When ordering a lab_test, you can see which markers each test orders. These can either be panels composed of multiple biomarkers or just individual biomarkers.

This means that a lab_test with only one associated marker, such as Lipid Panel, can return multiple result markers. We call these expected results. Each marker can thus be composed of multiple expected results which match to a loinc.

As an example, here’s the expected results for the Lipid Panel marker:

"expected_results":[
   {
      "id":1108,
      "name":"VLDL Cholesterol Cal",
      "slug":"vldl-cholesterol-cal",
      "lab_id":6,
      "provider_id":"011919",
      "loinc":{
         "id":5062,
         "name":"Cholesterol in VLDL Calc [Mass/Vol]",
         "slug":"cholesterol-in-vldl-calc-mass-vol",
         "code":"13458-5",
         "unit":"mg/dL"
      }
   },
   {
      "id":1109,
      "name":"Cholesterol, Total",
      "slug":"cholesterol-total",
      "lab_id":6,
      "provider_id":"001065",
      "loinc":{
         "id":11940,
         "name":"Cholesterol [Mass/Vol]",
         "slug":"cholesterol-mass-vol",
         "code":"2093-3",
         "unit":"mg/dL"
      }
   },
   {
      "id":1110,
      "name":"HDL Cholesterol",
      "slug":"hdl-cholesterol",
      "lab_id":6,
      "provider_id":"011817",
      "loinc":{
         "id":11858,
         "name":"Cholesterol in HDL [Mass/Vol]",
         "slug":"cholesterol-in-hdl-mass-vol",
         "code":"2085-9",
         "unit":"mg/dL"
      }
   },
   {
      "id":1112,
      "name":"Triglycerides",
      "slug":"triglycerides",
      "lab_id":6,
      "provider_id":"001172",
      "loinc":{
         "id":16384,
         "name":"Triglyceride [Mass/Vol]",
         "slug":"triglyceride-mass-vol",
         "code":"2571-8",
         "unit":"mg/dL"
      }
   },
   {
      "id":1113,
      "name":"LDL Chol Calc (NIH)",
      "slug":"ldl-chol-calc-nih",
      "lab_id":6,
      "provider_id":"012059",
      "loinc":{
         "id":5060,
         "name":"Cholesterol in LDL Calc [Mass/Vol]",
         "slug":"cholesterol-in-ldl-calc-mass-vol",
         "code":"13457-7",
         "unit":"mg/dL"
      }
   }
]

You can use this information to verify if the final results are composed of all expected results.

In order to obtain this data, you can use the following endpoints:

1. GET /v3/lab_tests/markers

   This allows you to search markers based on laboratory or name.

2. GET /v3/lab_tests/{id}/markers

   This allows you to see all markers associated with a lab test and it’s expected results.