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:

Get order results PDF
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.

The results field, according to the spec, can return either a list[BiomarkerResult] or an untyped dict. This is due to backwards compatibility, and you can disregard the untyped dict

​
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
provider_id: str | None
source_markers: List[ParentBiomarkerData] | 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.

The value field in deprecated and will eventually be removed.

​
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:

LabSlugLOINCLOINC Slug
Labcorphdl-cholesterol2085-9cholesterol-in-hdl-mass-vol
USSLhdl2085-9cholesterol-in-hdl-mass-vol

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.

​
Source Markers

As mentioned above, a marker can be composed of one or more results. This means that if you order a Lipid Panel, there will be no Lipid Panel result returned, but instead a series of markers that originate from the Lipid Panel.

Vital identifies the source marker via the source_markers field.

    {
      "name": "Sex Horm Binding Glob, Serum",
      "slug": "sex-horm-binding-glob-serum",
      "value": 30.4,
      "result": "30.4",
      "type": "numeric",
      "unit": "nmol/L",
      "timestamp": "2024-10-31T09:08:00+00:00",
      "notes": "Final",
      "min_range_value": 24.6,
      "max_range_value": 122,
      "is_above_max_range": false,
      "is_below_min_range": false,
      "interpretation": "normal",
      "loinc": "13967-5",
      "loinc_slug": "sex-hormone-binding-globulin-moles-vol",
      "provider_id": "082016",
      "source_markers": [
        {
          "marker_id": 229,
          "name": "Testosterone Free, Profile I",
          "slug": "testosterone-free-profile-i",
          "provider_id": "140226"
        }
      ]
    },

When Vital cannot identify the source, then this field will be null, indicating that this is an unsolicited result. There may also be more than one source marker, if there are two or more ordered markers that contain the same underlying result, using the same testing method.

​
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
source_markers: List[ParentBiomarkerData] | 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.

Partial Result NotificationsCritical Results