> ## Documentation Index > Fetch the complete documentation index at: https://docs.junction.com/llms.txt > Use this file to discover all available pages before exploring further. # Result Formats > Retrieve lab test results in two formats: raw PDF reports from partner labs and structured JSON data through the Junction API. Junction'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: ```bash Get order results PDF theme={null} curl --request GET \ --url {{BASE_URL}}/v3/order/{order_id}/result/pdf \ --header 'Accept: application/json' \ --header 'Content-Type: application/pdf' \ --header 'x-vital-api-key: ' ``` Some laboratories do not issue PDFs for partial results, and only provide PDF reports once all results are finalized. 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](/api-reference/lab-testing/results/get-results). 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. Junction 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.order.updated` event. This is done due to the possibility of [critical values](/lab/results/critical-results) 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.order.updated` webhook notification for this event. ### BiomarkerResult A `BiomarkerResult` has the following definition: ```python theme={null} name: str slug: str value: float # deprecated result: str type: ResultType unit: str | None timestamp: datetime | None notes: str | None reference_range: 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. 4. `ResultType.CODED_VALUE` - A coded value result using enum constants, e.g., `DETECTED`, `HEAD_AND_NECK` In this case, the `result` field will be an enum constant name, and the `value` field will be `-1`. This type is used for specialized tests like the Galleri multi-cancer early detection test. See the [Galleri Results](/lab/results/galleri-results) documentation for detailed information. The `value` field is 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](/lab/results/critical-results) section. #### Standardization - LOINC It's possible to test the same biomarkers across different laboratories. For these to match, we use the [LOINC](https://loinc.org/) 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 standardized version. An example: | Lab | Slug | LOINC | LOINC Slug | | ------- | --------------- | ------ | --------------------------- | | Labcorp | hdl-cholesterol | 2085-9 | cholesterol-in-hdl-mass-vol | | USSL | hdl | 2085-9 | cholesterol-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. LOINC codes may be missing in some results due to our LOINC compendium still being expanded and updated, labs providing data in formats our system does not recognize, or labs not including LOINC codes in their data at all. We are actively improving both the completeness of our compendium and our ability to interpret data variations, but missing LOINCs can still occur. Integrations should be built to handle cases where LOINC codes are not guaranteed. #### 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: ```json theme={null} "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](/api-reference/lab-testing/biomarkers) This allows you to search markers based on laboratory or name. 2. [GET /v3/lab\_tests/\{id}/markers](/api-reference/lab-testing/lab-test-markers) This allows you to see all markers associated with a lab test and its 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`. Junction identifies the source marker via the `source_markers` field. ```json theme={null} { "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 Junction 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 make mistakes, and expected results will be missing. Junction identifies these and parses them into a separate structure, named `missing_results`. This data has the following format: ```python theme={null} 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 Junction-assigned error type. The error type is inferred from the comments received from the lab. They are to help assess possible 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 a 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 unable to collect the proper volume of blood from the patient, 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 entire phlebotomy process, often immediately following the collection. For example, improper centrifugation of the collected sample or improper refrigeration. While these are the most likely causes, there are other reasons why sample quality may have been degraded. 3. `drop_off_failure` This speaks to a specific form of collection process failures. Specifically, the sample was not received by the lab in proper condition. Possible issues correspond to improper freezing, refrigeration, or exposure to excessive transport delay. 4. `internal_lab_failure` This speaks to failures that are most likely to have happened internally at the lab. This includes issues such as misplacing a collected sample, or errors that could not best be 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 that could not be properly attributed to any specific failure mode. Potentially the results were simply left out and Junction 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 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 — such as age — reported in AOE (ask on order entry) in order to be properly calculated.