Receiving Results | Medplum

How results arrive in Medplum

This guide explains how laboratory results are handled in the Medplum-Health Gorilla labs integration.

When Health Gorilla receives results from performing laboratories (Quest, Labcorp, regional labs, etc.), they are synchronized into your Medplum project as structured FHIR resources. The sections below describe the resulting data model and how results are matched to orders and patients.

Key Concepts

Understanding how results are structured and connected is essential for building clinical workflows and displaying results to providers.

FHIR Data Model

Laboratory results are represented as a suite of resources that preserve both structured and unstructured data for clinical workflows and original documentation for regulatory compliance.

In this section, we describe the primary resources used in Health Gorilla lab results.

Result Resource Types

DiagnosticReport

The DiagnosticReport serves as the primary container for all results related to a specific order, providing summary information and organizing individual observations.

Key Fields:

Example Structure:

{

"resourceType": "DiagnosticReport",

"identifier": [
    {
      "system": "https://www.healthgorilla.com",
      "value": "7890"
    },
    {
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "ACSN",
          "display": "Accession ID"
        }],
        "text": "Accession Number"
      },
      "value": "CF020052R"
    },
    {
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "PLAC",
          "display": "Placer"
        }],
        "text": "Placer"
      },
      "value": "1452503"
    }
  ],
  "status": "final",
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "58410-2",
      "display": "Complete blood count (CBC) panel"
    }]
  },
  "basedOn": [{
    "reference": "ServiceRequest/original-order-123"
  }],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "performer": [{
    "reference": "Organization/abcdef",
    "display": "Quest"
  }],
  "effectiveDateTime": "2025-06-27T00:41:00Z",
  "issued": "2025-06-30T15:34:54Z",
  "result": [{
    "reference": "Observation/wbc-count-456"
  },
  {
    "reference": "Observation/rbc-count-789"
  },
  {
    "reference": "Observation/clinical-lab-report-999"
  }],
  "presentedForm": [{
    "contentType": "application/pdf",
    "url": "https://storage.medplum.com/binary/123",
    "title": "DiagnosticReport-7890.pdf"
  }]
}

Observations

Individual lab values are represented as Observation resources, with each test result getting its own observation. Health Gorilla provides rich metadata including reference ranges, abnormal flags, and performing lab details.

Standard Lab Value Observations:

{
  "resourceType": "Observation",
  "status": "final",
  "identifier": [
    {
      "system": "https://www.healthgorilla.com",
      "value": "7890-6690-2"
    }
  ],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "code": {
    "coding": [{
      "system": "http://loinc.org",
      "code": "6690-2",
      "display": "Leukocytes [#/volume] in Blood by Automated count"
    }]
  },
  "valueQuantity": {
    "value": 7.2,
    "unit": "10*3/uL",
    "system": "http://unitsofmeasure.org"
  },
  "interpretation": [{
    "coding": [{
      "system": "http://terminology.hl7.org/CodeSystem/v2-0078",
      "code": "H",
      "display": "Above high normal"
    },
    {
      "system": "http://terminology.hl7.org/CodeSystem/v3-ObservationInterpretation",
      "code": "H",
      "display": "Above high normal"
    },
    {
      "system": "https://www.healthgorilla.com/observation-interpretation",
      "code": "H",
      "display": "Above high normal"
    }],
    "text": "Above high normal"
  }],
  "note": [{
    "text": "Fasting reference interval. "
  }],
  "referenceRange": [{
    "low": { "value": 4.5 },
    "high": { "value": 11.0 }
  }],
  "performer": [{
    "reference": "Organization/quest-lab-location-123"
  }]
}

DocumentReference

Unstructured PDF reports are stored as DocumentReference resources, with different types serving different purposes in the clinical workflow.

Health Gorilla Standard PDF:

• Referenced by DiagnosticReport.presentedForm
• Standardized format across all labs
• Optimized for electronic health record display

Lab-Branded PDFs:

• Referenced by the "clinical lab report" observation via derivedFrom
• Original lab formatting (Quest, Labcorp, regional lab branding)
• Preferred for patient communication and external sharing

{
  "resourceType": "DocumentReference",
  "status": "current",
  "docStatus": "final",
  "category": [{
    "coding": [{
      "system": "https://www.medplum.com/integrations/health-gorilla/document-type",
      "code": "DiagnosticReport"
    }]
  }],
  "subject": {
    "reference": "Patient/4556",
    "display": "Homer Simpson"
  },
  "identifier": [{
    "system": "https://www.healthgorilla.com",
    "value": "123456"
  }],
  "content": [{
    "attachment": {
      "contentType": "application/pdf",
      "url": "https://storage.medplum.com/binary/87654",
      "title": "DiagnosticReport-123456.pdf"
    }
  }]
}

Detected Issues

The Medplum Health Gorilla integration creates DetectedIssue resources to flag clinical workflow concerns.

Common Issue Types:

{
  "resourceType": "DetectedIssue",
  "code": {
    "coding": [{
      "system": "https://www.medplum.com/integrations/health-gorilla/issue-type",
      "code": "unsolicited-diagnostic-report"
    }]
  },
  "implicated": [{
    "reference": "DiagnosticReport/123abc"
  }]
}

Organizations

Health Gorilla returns detailed information about the performing laboratory for each observation. If the corresponding lab does not exist inside your Medplum project, receive-from-health-gorilla will create the corresponding Organization resource and link it to each observation.

Key Information Captured:

• Lab name and location details
• Physical address
• Lab director contact information

{
  "resourceType": "Organization",
  "name": "Quest Diagnostics - Regional Lab 123",
  "address": [{
    "line": ["1234 Lab Drive"],
    "city": "San Francisco",
    "state": "CA",
    "postalCode": "94102"
  }],
  "partOf": {
    "reference": "Organization/quest-lab-location-123",
    "display": "Quest"
  },
  "contact": [{
    "purpose": {
      "coding": [{
        "system": "http://hl7.org/fhir/contactentity-type",
        "code": "ADMIN"
      }]
    },
    "name": {
      "text": "Ronald McDonald CLS"
    }
  }],
}

Resolving Orders with Results

When a result is received, Medplum attempts to match it to an existing order (ServiceRequest).

Processing Logic:

1. receive-from-health-gorilla first attempts to match the incoming result to an existing order by checking:
   • basedOn references (which contain the requisition ID)
   • Accession number (ACSN identifier): A unique identifier assigned by the performing laboratory (e.g., Quest, Labcorp) to the specific specimen(s) when they are received and logged into their system.
   • Placer number (PLAC identifier): The order ID assigned by the ordering system (e.g., your EMR, Medplum, or the clinic) that placed the order.
   • Filler number (FILL identifier): The order ID assigned by the fulfilling system (the performing laboratory) that carries out the order.
2. If a matching order is found, the result is linked to that order. The patient associated with that order is used, preventing duplicate patients or unknown-patient issues.
3. If no matching order is found, the result is considered "unsolicited". The bot then attempts to match the result to a patient using the patient's Health Gorilla identifier.
4. If a matching patient exists, the result is imported normally, but without a DiagnosticReport.basedOn reference, and a DetectedIssue with code unsolicited-diagnostic-report is created.
5. If no patient match is found, a new Patient resource is created using the demographic information provided by the lab, and a DetectedIssue with code unknown-patient is created.

Backfilling missed results

If results are missing in Medplum but visible in the Health Gorilla portal, check that subscriptions are active (setup-subscriptions) and that the callback bot URL is current. When webhooks were down or never configured for a period, use sync-resources-from-health-gorilla to backfill:

1. Choose a startDate and endDate that bracket the gap (based on _lastUpdated in Health Gorilla).
2. Run a DiagnosticReport sync with syncOnlyMissing: true to avoid re-processing resources already in Medplum.
3. Review DetectedIssue resources for any remaining unsolicited or unknown-patient cases, especially in receive-only migrations without placeholder orders.

For receive-only migrations, syncing placeholder ServiceRequest orders with matching Placer or Accession identifiers before backfilling results reduces unsolicited reports.

Lab-specific Behavior

Quest

• Preliminary Results: Quest sends preliminary results on a rolling basis, and will send the same report multiple times, updating Medplum's DiagnosticReport resource in-place. Monitor the value of DiagnosticReport.status to see when the report has been finalized. The same in-place updates apply when the report is imported via manual sync.