Lab Report Parsing

Junction’s Lab Report Parsing API converts lab report files into structured JSON. You can upload PDF, JPEG, and PNG reports from external laboratories, patient-uploaded records, or historical chart archives, then retrieve extracted metadata, results, reference ranges, interpretations, and LOINC matches. Lab Report Parsing is separate from Junction’s ordered lab test workflow. It does not place an order, collect a sample, or request a result from a lab. It reads an existing report document and returns the data Junction can extract from that document.

This feature is in closed beta.Interested in this feature? Get in touch with your Customer Success Manager.

When to Use It

Use Lab Report Parsing when you already have a completed lab report file and need to make it usable in your application. Common use cases include:

Patient uploads of lab reports from outside providers
Historical data imports from PDFs or scanned records
Multi-lab result aggregation using LOINC as a normalization layer
Backfilling structured results before a user starts ordering through Junction

If the result came from a Junction lab order, use the order result format documentation and results endpoints instead.

Workflow

The parsing workflow is asynchronous:

Upload one or more report files to create a parsing job.
Junction validates and stages the uploaded file, then queues the parsing job.
Junction extracts report metadata and lab results, then attempts to match extracted results to LOINC codes.
Your application receives a webhook or polls the job endpoint.
When the job is completed, the data object contains parsed metadata and results.

Uploading Reports

Create a parsing job with the Create Lab Report Parser Job endpoint. The request is multipart/form-data and requires:

Field	Required	Description
`file`	Yes	One lab report file, or multiple image files for one report.
`user_id`	Yes	Junction user ID to associate with the parsed report.
`needs_human_review`	No	Set to `true` to request manual review where enabled for your team. Defaults to `false`.

Supported file formats and upload limits:

Upload	Supported formats	Limit
Single file	PDF, JPEG, or PNG	30 MiB
Multiple files	JPEG and PNG only	Up to 8 files and 30 MiB combined
PDF pages	PDF upload	Up to 30 pages

When you upload multiple image files, Junction treats each image as one page and merges the files into a single PDF in the order supplied. Multi-file uploads cannot include PDFs. Each individual file must also be no larger than 30 MiB, although the 30 MiB combined limit is normally the effective limit for a multi-file request. Junction validates the declared Content-Type and file signature for every file. It also verifies that PDFs can be read and decodes images in multi-file uploads while merging them. A file that passes synchronous upload validation can still fail later during asynchronous parsing.

cURL

curl --request POST \
     --url {{BASE_URL}}/lab_report/v1/parser/job \
     --header 'accept: application/json' \
     --header 'x-vital-api-key: <YOUR_API_KEY>' \
     --header 'Content-Type: multipart/form-data' \
     --form 'file=@/path/to/lab_report.pdf' \
     --form 'user_id=<USER_ID>' \
     --form 'needs_human_review=false'

The create response returns the job immediately. At this point, data is null because parsing has not completed.

Response

{
  "id": "8eb0217f-4683-4a3c-adca-faf95ac65739",
  "status": "upload_pending",
  "failure_reason": null,
  "data": null,
  "needs_human_review": false,
  "is_reviewed": false
}

Job Statuses

The status field describes the state of the parsing job.

Status	Description
`upload_pending`	Job was created and the file upload is being finalized. This is the status returned by the create endpoint.
`started`	The file was uploaded and parsing is in progress.
`completed`	Parsing completed and results are available in `data`.
`failed`	Parsing failed. Check `failure_reason` for more information.

If a parsing job fails, failure_reason can include:

Failure reason	Meaning
`invalid_input`	The parser determined that the document is not a lab report containing medical test results.
`not_english`	The report language is not supported.
`processing_error`	Junction could not process the report because of an internal parser or provider failure.

Parser status and failure reason enums are non-exhaustive. Store unknown values safely and avoid hard-failing if Junction adds a new value or returns failure_reason: null.

Upload Validation Errors

Some invalid uploads are rejected synchronously by the create endpoint instead of becoming failed parser jobs. These errors return an HTTP error response before a parsing job is created.

Upload issue	Response behavior
Unsupported file type	`400` error before parsing starts.
Empty file	`400` error before parsing starts.
Declared `Content-Type` does not match file bytes	`400` error before parsing starts.
More than 8 files	`400` error before parsing starts.
Multiple files include a PDF	`400` error before parsing starts.
An image in a multi-file upload cannot be decoded	`400` error before parsing starts.
File is larger than the upload limit	`413` error before parsing starts.
Combined upload is larger than 30 MiB	`413` error before parsing starts.
PDF is corrupted, truncated, or unreadable	`400` error before parsing starts.
PDF exceeds the page limit	`400` error before parsing starts.

Human Review

Set needs_human_review to true to request manual review where enabled for your team. Do not use this field as a substitute for your application’s own clinical review or validation requirements. Human review is not enabled for every team by default. Contact your account manager before depending on it in production. If your team is not enabled for human review, creating a job with needs_human_review=true returns a 400 response:

Error

{
  "detail": "Human review is not supported yet for your team please contact support"
}

The response includes two review fields:

Field	Meaning
`needs_human_review`	Whether the job was submitted with a manual-review request.
`is_reviewed`	Whether Junction has recorded the requested manual review as completed.

Parsed Output

When status is completed, data contains:

Field	Description
`metadata`	Patient and report-level metadata extracted from the document.
`results`	Array of extracted lab results. Each item represents one reported marker or observation.

Example completed response:

Response

{
  "id": "8eb0217f-4683-4a3c-adca-faf95ac65739",
  "status": "completed",
  "failure_reason": null,
  "data": {
    "metadata": {
      "patient_first_name": "Jane",
      "patient_last_name": "Doe",
      "dob": "1990-01-01",
      "gender": "female",
      "lab_name": "Acme Labs",
      "date_reported": "2025-01-01",
      "date_collected": "2024-12-30",
      "specimen_number": "ABC123"
    },
    "results": [
      {
        "test_name": "Glucose",
        "value": "90",
        "type": "numeric",
        "units": "mg/dL",
        "min_reference_range": 70,
        "max_reference_range": 99,
        "source_panel_name": "CMP",
        "sample_type": "serum_plasma_blood",
        "measurement_kind": "direct",
        "sensitivity": "unknown",
        "loinc_match_status": "auto_match",
        "loinc_matches": [
          {
            "loinc_code": "2345-7",
            "loinc_name": "Glucose [Mass/volume] in Serum or Plasma",
            "display_name": "Glucose",
            "aliases": [],
            "confidence_score": 0.99
          }
        ],
        "interpretation": "normal",
        "is_above_max_range": false,
        "is_below_min_range": false
      }
    ]
  },
  "needs_human_review": false,
  "is_reviewed": false
}

Metadata

metadata is extracted from the document header and surrounding report content when present.

Field	Description
`patient_first_name`	Patient first name from the report.
`patient_last_name`	Patient last name from the report.
`dob`	Patient date of birth extracted from the report.
`gender`	Extracted patient gender normalized to `male`, `female`, or `other`.
`lab_name`	Name of the lab or reporting organization.
`date_reported`	Date the report was issued.
`date_collected`	Date the specimen was collected.
`specimen_number`	Lab specimen, accession, or sample identifier.

Not every report contains every metadata field. Treat patient names, date of birth, lab name, report dates, and specimen number as nullable. Treat unknown or unsupported gender values as other. Date fields are strings and are not guaranteed to use one date format. Parse them only after validating the returned value.

Result Fields

Each data.results[] item contains the extracted value and associated context.

Field	Description
`test_name`	Marker or observation name extracted from the report.
`value`	Result value as a string. See Value and Type.
`type`	Result shape, such as `numeric`, `range`, or `comment`.
`units`	Units extracted from the report, when available.
`min_reference_range`	Numeric lower bound extracted from the reference range, when available.
`max_reference_range`	Numeric upper bound extracted from the reference range, when available.
`source_panel_name`	Panel name associated with the result, when available.
`sample_type`	Specimen type, such as `serum_plasma_blood`, `urine`, `saliva`, `stool`, `capillary_blood`, `other`, or `unknown`.
`measurement_kind`	Whether the result appears to be `direct`, `calculated`, `ratio`, or `unknown`.
`sensitivity`	Assay sensitivity classification: `sensitive`, `insensitive`, or `unknown`. Defaults to `unknown`.
`interpretation`	Parsed or inferred interpretation. Possible values are `normal`, `abnormal`, `critical`, or `unknown`.
`is_above_max_range`	Whether the result is above `max_reference_range`, when this can be determined.
`is_below_min_range`	Whether the result is below `min_reference_range`, when this can be determined.
`loinc_match_status`	LOINC matching state: `auto_match`, `needs_review`, or `no_match`.
`loinc_matches`	Candidate LOINC matches with confidence scores.

Value and Type

data.results[].value is always returned as a string. Do not assume it can always be parsed as a number. For type: "numeric", value should be a number encoded as a string, such as "5" or "5.0". For other result types, value can contain comparators, text, boolean-like values, durations, percentages, or ratios. Use type before deciding how to parse or display the value.

Type	Example `value`	Notes
`numeric`	`"90"`, `"1e-3"`	Numeric result encoded as a string. Use `units` for measurement units.
`range`	`"<5"`, `">=10"`, `"≤1e-3"`, `"3-7"`	May include comparators, approximate values, scientific notation, or lower-to-upper range notation. Do not parse as a plain float.
`comment`	`"See note"`, `"Unable to calculate"`	Textual result or observation.
`boolean`	`"true"`, `"false"`, `"yes"`, `"no"`, `"positive"`, `"negative"`	Boolean or presence-style findings can vary by report wording.
`duration`	`"3h"`, `"12 min"`, `"10:00"`	Duration-like values are preserved as strings because reports can use different formats.
`percentage`	`"5.4%"`	Inferred when the value includes `%`. If the value is `"5.4"` and `units` is `%`, the result may be returned as `numeric`; read `value`, `type`, and `units` together.
`ratio`	`"97/100"`	Slash-form ratios are inferred when `type` is not already supplied. Other ratio-like formats, such as colon-form titers, may be returned as `comment`.

The parser output is optimized to preserve what was reported. Store the raw value string and derive typed values in your application only after checking type, units, and reference range fields.

The parser-specific type values are related to, but not identical to, the order result ResultType values documented in Result Formats. Parser results currently include numeric, range, comment, boolean, duration, percentage, and ratio. When type is not supplied by extraction, Junction infers it from value. For example, "<50", "≥2000", and "10-20" are inferred as range; "20%" is inferred as percentage; "97/100" is inferred as ratio; and unrecognized text is inferred as comment.

Reference Ranges and Interpretation

The parser may extract min_reference_range and max_reference_range as numeric bounds when the report includes a parseable reference range. It may also return:

interpretation: possible values are normal, abnormal, critical, or unknown.
is_above_max_range: whether the result is above the extracted maximum
is_below_min_range: whether the result is below the extracted minimum

These fields depend on the quality and structure of the source report. Some reports include clear numeric bounds; others include textual ranges, age-specific ranges, sex-specific ranges, comments, or formatting that cannot be normalized into numeric bounds. For numeric values, Junction can infer whether the result is above or below the extracted numeric reference bounds. For comparator range values, Junction only sets range flags when the comparator is conclusive. For example, ">2000" with a max reference range of 1100 is above range, but ">500" with the same max is inconclusive. If a value is conclusively outside the extracted bounds, interpretation is abnormal. Numeric values without an out-of-range flag are interpreted as normal. Non-numeric and inconclusive range values are interpreted as unknown unless the parser extracted a more specific interpretation. If you need custom boundary logic, read the result value, type, units, and reference range fields together. For general order-result reference range guidance, see Reference Range.

LOINC Matching

Junction attempts to match extracted results to LOINC codes so you can compare markers across different labs and report formats. Each loinc_matches[] item includes:

Field	Description
`loinc_code`	LOINC code, such as `2345-7`.
`loinc_name`	Official or normalized LOINC name.
`display_name`	Display label for the match.
`aliases`	Alternate names associated with the match.
`confidence_score`	Relative score for this LOINC candidate. Candidates are returned in descending score order, with up to five matches per result.

confidence_score is a matching score for the candidate LOINC code. It is not an accuracy score for the extracted lab result, patient metadata, units, reference ranges, or interpretation. A high score means Junction’s LOINC matcher found a stronger candidate for that result row than lower-scored candidates; it does not prove that the source document was parsed correctly. In most integrations, use loinc_match_status for workflow decisions instead of building your own thresholds on confidence_score. Store the score for debugging, audit, or support workflows, but avoid using it as a clinical-confidence or result-accuracy signal. Use loinc_match_status to decide how much review your workflow needs:

Status	Meaning
`auto_match`	Junction found a likely LOINC match.
`needs_review`	Junction found possible matches, but review is recommended.
`no_match`	Junction could not identify a match.

LOINC matches are not guaranteed for every extracted result. Your integration should handle loinc_matches: null, an empty match list, low confidence scores, needs_review, no_match, and future match statuses.

Webhooks

Subscribe to parser events to avoid polling.

Event	Trigger
`lab_report.parsing_job.created`	A new parsing job was created.
`lab_report.parsing_job.updated`	A parsing job changed status, including completion or failure.

The POST response is produced from the initial job record and returns upload_pending. After Junction stages the file, the lab_report.parsing_job.created webhook contains the same job in started status. A later lab_report.parsing_job.updated webhook contains the terminal completed or failed state. Webhook delivery is asynchronous, so your application should not depend on receiving events in the same order as API responses. Webhook payloads include the user, team, and parsing job:

Webhook payload

{
  "event_type": "lab_report.parsing_job.updated",
  "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "client_user_id": "7cbd6f62-0d22-4e5f-b7fd-bc4ee5c3fd8d",
  "team_id": "6353bcab-3526-4838-8c92-063fa760fb6b",
  "data": {
    "id": "8eb0217f-4683-4a3c-adca-faf95ac65739",
    "status": "completed",
    "failure_reason": null,
    "data": {
      "metadata": {
        "patient_first_name": "Jane",
        "patient_last_name": "Doe",
        "dob": "1990-01-01",
        "gender": "female",
        "lab_name": "Acme Labs",
        "date_reported": "2025-01-01",
        "date_collected": "2024-12-30",
        "specimen_number": "ABC123"
      },
      "results": [
        {
          "test_name": "Glucose",
          "value": "90",
          "type": "numeric",
          "units": "mg/dL",
          "min_reference_range": 70,
          "max_reference_range": 99,
          "loinc_match_status": "auto_match",
          "loinc_matches": [
            {
              "loinc_code": "2345-7",
              "loinc_name": "Glucose [Mass/volume] in Serum or Plasma",
              "display_name": "Glucose",
              "aliases": [],
              "confidence_score": 0.99
            }
          ],
          "interpretation": "normal",
          "is_above_max_range": false,
          "is_below_min_range": false
        }
      ]
    },
    "needs_human_review": false,
    "is_reviewed": false
  }
}

For webhook delivery behavior, retries, and event structure, see Webhooks.

Sandbox Limits

Sandbox lab report parsing has a limit of 300 non-failed jobs per team. Jobs in upload_pending, started, or completed count toward the limit. Jobs with status: "failed" or a non-null failure_reason do not count. When the sandbox limit is reached, the response is:

Error

{
  "detail": "Sandbox lab report parsing is limited to 300 reports. Please upgrade your contract to continue."
}

This is a team-wide sandbox usage limit, not a per-user or file-level validation error. Retrying the same request, creating more users, or changing the report file does not reset it. Production access is enabled per team and does not use the sandbox job-count check. Contact Junction support if you need higher-volume testing or production access.

Integration Guidance

Build your parser integration defensively:

Keep the original report file or a pointer to it in your system for audit and reprocessing workflows.
Store data.results[].value as a string, even when type is numeric.
Treat parser enums as non-exhaustive and log unknown status, type, failure_reason, sample_type, measurement_kind, and loinc_match_status values.
Do not require LOINC matches to be present before displaying the extracted result to users.
Review low-confidence or needs_review LOINC matches before using them for clinical decisioning, cohort logic, or automated recommendations.
Expect null metadata and null reference range fields when the source report does not include parseable values.
Use webhooks for normal processing and keep polling as a fallback for missed events or manual support flows.

Getting Started

Ordering Workflows

Walk-in (Patient Service Center) Orders

Mobile Phlebotomy Orders

At-Home Test Kit Orders

On-site Collection Orders

Results and Follow-up