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.

​

Missing Results

At times labs will commit mistakes, and expected results will be missing. Vital identifies these and parses them into a separate structure, named missing_results.

This data has the following format:

name: str
slug: str
inferred_failure_type: FailureType
note: str | None = None
loinc: str | None = None
loinc_slug: str | None = None
provider_id: str | None = None

inferred_failure_type is the Vital assigned error type. The error type is inferred from the comments received from the lab. They are to help assess possibly root causes of missing results, and aid the customer in identifying issues in aggregate. The way that we infer these error types is subject to change as we continue to refine and achieve more granular understanding of failure modes.

1. quantity_not_sufficient_failure

   The lab could not process this result due to an insufficient quantity of collected sample. This could be due to the patient refusing to collect more, the phlebotomist being to unable to collect the proper volume of blood from the sample, or the phlebotomist not collecting all of the sample they were meant to collect.

2. collection_process_failure

   This is indicative of potential failures to follow the entirety phlebotomy process, often immediately following the collection. For example, improper centrifugation of the collected sample, improper refrigeration. While these are the most likely causes, there are other reasons for why sample quality may have been degraded.

3. drop_off_failure

   This speaks to a specific form of collection process failures. Specifically that the sample was not received by the lab in proper condition. Possible issues correspond to improper freezing, or refrigeration, or was exposed to excessive transport delay.

4. internal_lab_failure

   This speaks to failures that are most likely to have happened internal to the lab. This includes issues such as misplacing a collected sample, or errors that could not be best attributed to any external cause.

5. order_entry_failure

   The test was not performed because it was not properly ordered at the lab.

6. non_failure

   This speaks to a failure that should not impact the patient. For example, it may indicate that a duplicate test was ordered.

7. unknown_failure

   This is a failure mode that could not be properly attributed to any specific failure mode. Potentially the results were simply left out and Vital was not provided any additional information.

8. patient_condition_failure

   This speaks to a failure to result due to specifics of the patient’s physical condition. For example, the patient may have had some food very high in fats that immediately prior to a collection. It is possible that improper storage and handling can cause samples to fail in ways that appear to be a patient condition failure.

9. missing_result_calc_failure

   This failure indicates that a calculated field is missing because the underlying tests required to perform the calculation were either unable to be processed, or yielded a result outside of the allowable parameters to perform the calculation

10. missing_demo_aoe_calc_failure

Some results may require additional information reported in AOE (ask on order entry) in order to yield results, such as age, to be properly calculated.